Add database management commands to Prisma CLI

docs/product/command-principles.md

@@ -38,7 +38,7 @@ The long-term command surface grows through workflow groups such as:
 - `app`
 - `git`
 
-The preview implements only `auth`, `project`, `git`, `branch`, and `app`.
+The preview implements only `auth`, `project`, `git`, `branch`, `database`, and `app`.
 
 ## Stable Nouns
 

docs/product/command-spec.md

@@ -14,6 +14,7 @@ The beta package includes these command groups:
 - `project` (includes `project env` subgroup)
 - `git`
 - `branch`
+- `database` (includes `database connection` subgroup)
 - `app`
 
 The beta package also includes one top-level utility command:
@@ -29,7 +30,6 @@ Out of scope for the current beta:
 
 - `init`
 - `schema`
-- `database`
 - `migrate`
 - product-specific namespaces such as `compute`
 
@@ -551,6 +551,177 @@ prisma-cli branch list
 prisma-cli branch list --json
 ```
 
+## `prisma-cli database list --project <id-or-name> --branch <git-name>`
+
+Purpose:
+
+- list Prisma Postgres databases for the resolved project
+
+Behavior:
+
+- requires auth and resolved project context; accepts `--project <id-or-name>` as an explicit fallback
+- lists database metadata only: name, id, branch, region, status, and created timestamp when available
+- `--branch <git-name>` narrows the list to databases attached to that Branch
+- never prints or returns connection strings, passwords, or endpoint secrets
+- does not create, delete, or mutate remote state
+- uses the standard list JSON envelope with redacted database metadata
+
+Examples:
+
+```bash
+prisma-cli database list
+prisma-cli database list --branch feature/foo
+prisma-cli database list --json
+```
+
+## `prisma-cli database show <database> --project <id-or-name> --branch <git-name>`
+
+Purpose:
+
+- show metadata for one Prisma Postgres database
+
+Behavior:
+
+- requires auth and resolved project context; accepts `--project <id-or-name>` as an explicit fallback
+- resolves `<database>` by exact database id or exact database name inside the resolved project
+- `--branch <git-name>` narrows name resolution when the same database name exists on multiple Branches
+- returns database metadata and connection metadata only
+- never prints or returns connection strings, passwords, or endpoint secrets
+- fails with `DATABASE_NOT_FOUND` or `DATABASE_AMBIGUOUS` when the target cannot be selected safely
+
+Examples:
+
+```bash
+prisma-cli database show db_123
+prisma-cli database show acme-preview --branch preview
+prisma-cli database show db_123 --json
+```
+
+## `prisma-cli database create <name> --project <id-or-name> --branch <git-name> --region <region>`
+
+Purpose:
+
+- create a Prisma Postgres database and return its first one-time connection URL
+
+Behavior:
+
+- requires auth and resolved project context; accepts `--project <id-or-name>` as an explicit fallback
+- creates an empty Prisma Postgres database in the resolved project
+- `--branch <git-name>` targets the created database to a Branch when supplied
+- `--region <region>` passes the Prisma Postgres region id when supplied
+- the Management API returns the first connection as a one-time-view secret
+- in human mode, stdout contains exactly one line: the raw connection URL
+- human stderr does not repeat, label, or wrap the connection URL
+- in `--json`, `result.connectionString` contains the raw one-time URL exactly once
+- no `DATABASE_URL=` or `DIRECT_URL=` formatting is added; consumers decide how to store the URL
+
+Examples:
+
+```bash
+prisma-cli database create my-db
+prisma-cli database create my-db --branch feature/foo --region eu-central-1
+prisma-cli database create my-db --json
+```
+
+## `prisma-cli database remove <database> --confirm <database-id>`
+
+Purpose:
+
+- remove a Prisma Postgres database
+
+Behavior:
+
+- requires auth and resolved project context; accepts `--project <id-or-name>` as an explicit fallback
+- resolves `<database>` by exact database id or exact database name inside the resolved project
+- requires `--confirm <database-id>` where the value exactly matches the resolved database id
+- `--yes` does not satisfy this confirmation
+- removes the database and its connection metadata through the Management API
+- never prints or returns connection strings, passwords, or endpoint secrets
+
+Examples:
+
+```bash
+prisma-cli database remove db_123 --confirm db_123
+```
+
+## `prisma-cli database connection`
+
+Manage one-time-view connection strings for a database.
+
+`connection` is nested under `database` because connection strings are only
+valid in the context of a Prisma Postgres database. The subgroup mirrors the
+`project env <action>` shape: the parent command names the resource family,
+the nested noun names the subordinate resource, and the final token is the
+action. There is no `database connection show` command because connection
+strings are one-time-view secrets.
+
+### `prisma-cli database connection list <database>`
+
+Purpose:
+
+- list connection metadata for a database
+
+Behavior:
+
+- requires auth and resolved project context; accepts `--project <id-or-name>` as an explicit fallback
+- resolves `<database>` by exact database id or exact database name inside the resolved project
+- supports `--branch <git-name>` to narrow database name resolution
+- lists connection names, ids, and created timestamps when available
+- never prints or returns connection strings, passwords, or endpoint secrets
+
+Examples:
+
+```bash
+prisma-cli database connection list db_123
+prisma-cli database connection list acme-preview --branch preview
+prisma-cli database connection list db_123 --json
+```
+
+### `prisma-cli database connection create <database> --name <name>`
+
+Purpose:
+
+- create a new one-time-view connection URL for a database
+
+Behavior:
+
+- requires auth and resolved project context; accepts `--project <id-or-name>` as an explicit fallback
+- resolves `<database>` by exact database id or exact database name inside the resolved project
+- supports `--branch <git-name>` to narrow database name resolution
+- `--name <name>` sets the connection metadata name; when omitted, the CLI generates a `cli-YYYYMMDDhhmmssSSS-xxxx` name
+- in human mode, stdout contains exactly one line: the raw connection URL
+- human stderr does not repeat, label, or wrap the connection URL
+- in `--json`, `result.connectionString` contains the raw one-time URL exactly once
+- no `DATABASE_URL=` or `DIRECT_URL=` formatting is added; consumers decide how to store the URL
+
+Examples:
+
+```bash
+prisma-cli database connection create db_123
+prisma-cli database connection create db_123 --name readonly
+prisma-cli database connection create db_123 --json
+```
+
+### `prisma-cli database connection remove <connection> --confirm <connection-id>`
+
+Purpose:
+
+- remove a database connection
+
+Behavior:
+
+- requires auth
+- treats `<connection>` as the connection id to remove
+- requires `--confirm <connection-id>` where the value exactly matches the connection id
+- `--yes` does not satisfy this confirmation
+- never prints or returns connection strings, passwords, or endpoint secrets
+
+Examples:
+
+```bash
+prisma-cli database connection remove conn_123 --confirm conn_123
+```
+
 ## `prisma-cli app build --entry <path> --build-type <auto|bun|nextjs|nuxt|astro|tanstack-start>`
 
 Purpose:

docs/product/error-conventions.md

@@ -143,7 +143,7 @@ Rules:
 - `ok` is always `false`
 - `command` is always present
 - `error.code` is stable and machine-readable
-- `error.domain` is a stable logical area such as `cli`, `auth`, `project`, `branch`, or `app`
+- `error.domain` is a stable logical area such as `cli`, `auth`, `project`, `branch`, `app`, or `database`
 - `error.severity` is stable and machine-readable
 - `error.summary` is the short human-readable headline
 - `error.why` explains the immediate cause when known
@@ -197,6 +197,12 @@ These codes are the minimum stable set for the MVP:
 - `BUILD_FAILED`
 - `BRANCH_DATABASE_SETUP_FAILED`
 - `SCHEMA_SETUP_FAILED`
+- `DATABASE_NOT_FOUND`
+- `DATABASE_AMBIGUOUS`
+- `DATABASE_CONNECTION_NOT_FOUND`
+- `DATABASE_CONNECTION_MISSING`
+- `DATABASE_CONNECTION_STRING_MISSING`
+- `DATABASE_API_ERROR`
 - `RUN_FAILED`
 - `DEPLOY_FAILED`
 - `VERSION_UNAVAILABLE`
@@ -243,6 +249,12 @@ Recommended meanings:
 - `BUILD_FAILED`: build failed before a healthy deployment existed
 - `BRANCH_DATABASE_SETUP_FAILED`: database creation or env-var wiring failed before deployment started
 - `SCHEMA_SETUP_FAILED`: local Prisma schema source setup against a newly created database failed before deployment started
+- `DATABASE_NOT_FOUND`: requested database id or name does not exist in the resolved project scope
+- `DATABASE_AMBIGUOUS`: requested database name matches multiple databases and needs an id or branch filter
+- `DATABASE_CONNECTION_NOT_FOUND`: requested database connection id does not exist or is not accessible
+- `DATABASE_CONNECTION_MISSING`: database creation succeeded but the API response did not include the first one-time connection payload
+- `DATABASE_CONNECTION_STRING_MISSING`: connection creation succeeded but the API response did not include the one-time connection string
+- `DATABASE_API_ERROR`: database Management API request failed without a more specific CLI error code
 - `RUN_FAILED`: local framework run command could not be started or exited unsuccessfully
 - `DEPLOY_FAILED`: deployment or post-build health failed
 - `VERSION_UNAVAILABLE`: CLI could not read its own bundled package metadata to report a version (defensive; not expected in normal installs)

docs/product/output-conventions.md

@@ -104,9 +104,30 @@ Current MVP commands map to patterns like this:
 | `git connect` | `mutate` |
 | `git disconnect` | `mutate` |
 | `branch list` | `list` |
+| `database list` | `list` |
+| `database show` | `show` |
+| `database create` | raw secret stdout + JSON envelope |
+| `database remove` | `mutate` |
+| `database connection list` | `list` |
+| `database connection create` | raw secret stdout + JSON envelope |
+| `database connection remove` | `mutate` |
 
 No current MVP command uses `verify` or `inspect`, but new commands must still choose one existing pattern rather than inventing a new one casually.
 
+### One-Time Secret Output
+
+Commands that create one-time-view secrets may write the raw secret value to
+stdout in human mode. This is still machine-readable output, not decorative
+human output.
+
+Rules:
+
+- write exactly one raw secret value per successful create command
+- do not repeat the secret on stderr
+- do not wrap the secret in labels such as `DATABASE_URL=`
+- list and show commands must never print or return secret values
+- in `--json`, include the secret exactly once in the result object
+
 ### Shared Patterns
 
 #### `list`

docs/product/resource-model.md

@@ -154,14 +154,36 @@ top-level target-context group is `branch`, not `env`.
 `schema` stays a local code artifact. `database` stays a branch-bound remote
 resource.
 
-The beta package does not expose a standalone database command group yet. The
-current database surface is limited to `app deploy --db`, which can create an
-empty Prisma Postgres database, apply a supported local Prisma schema source
-when available, and write normal environment variables for the deploy target.
+The beta package exposes `database` as the canonical database management group.
+The first slice manages Prisma Postgres database metadata and one-time-view
+connection strings:
+
+- `database list`
+- `database show <database>`
+- `database create <name>`
+- `database remove <database>`
+- `database connection list <database>`
+- `database connection create <database>`
+- `database connection remove <connection>`
+
+The `database connection` subgroup is nested because connection strings exist
+only for databases. It follows the same parent-noun/subordinate-noun/action
+shape as `project env <action>`. There is no `database connection show` command:
+connection strings are secrets and the platform returns them only during create
+operations.
 
 Rules:
 
+- `database` is the canonical public group; Public Beta does not add public
+  `db` or `postgres` aliases
+- `database create` prints the first returned connection URL exactly once
+- `database connection create` prints the created connection URL exactly once
+- create commands print raw URLs only, never `DATABASE_URL=` or `DIRECT_URL=`
 - database wiring uses the existing environment-variable model
+- `database list`, `database show`, and `database connection list` never print
+  or return secret values
+- database and database connection removal require exact id confirmation with
+  `--confirm <id>`; `--yes` is not sufficient
 - preview Branch setup writes branch-scoped `DATABASE_URL` and `DIRECT_URL` overrides, not separate app bindings
 - first production deploy setup writes production `DATABASE_URL` and `DIRECT_URL` env vars before the App has a live deployment
 - database setup never overwrites an existing branch-scoped `DATABASE_URL`

packages/cli/fixtures/mock-api.json

@@ -132,5 +132,56 @@
       "status": "ready",
       "url": "https://preview.billing-api.prisma.app"
     }
+  ],
+  "databases": [
+    {
+      "id": "db_123",
+      "projectId": "proj_123",
+      "branchId": "br_123",
+      "branchName": "preview",
+      "name": "acme-preview",
+      "region": "eu-central-1",
+      "status": "ready",
+      "isDefault": true,
+      "createdAt": "2026-06-01T00:00:00.000Z"
+    },
+    {
+      "id": "db_456",
+      "projectId": "proj_123",
+      "branchId": "br_456",
+      "branchName": "production",
+      "name": "acme-production",
+      "region": "us-east-1",
+      "status": "ready",
+      "isDefault": false,
+      "createdAt": "2026-06-02T00:00:00.000Z"
+    },
+    {
+      "id": "db_789",
+      "projectId": "proj_456",
+      "branchId": "br_789",
+      "branchName": "preview",
+      "name": "billing-preview",
+      "region": "eu-central-1",
+      "status": "ready",
+      "isDefault": false,
+      "createdAt": "2026-06-03T00:00:00.000Z"
+    }
+  ],
+  "databaseConnections": [
+    {
+      "id": "conn_123",
+      "databaseId": "db_123",
+      "name": "primary",
+      "createdAt": "2026-06-01T00:00:00.000Z",
+      "connectionString": "postgresql://secret-preview.example.prisma.io/postgres"
+    },
+    {
+      "id": "conn_456",
+      "databaseId": "db_456",
+      "name": "primary",
+      "createdAt": "2026-06-02T00:00:00.000Z",
+      "connectionString": "postgresql://secret-production.example.prisma.io/postgres"
+    }
   ]
 }