feat(cli): add database usage, backup list, restore, and connection rotate

Extends the database group with the remaining Management API surface:

- database usage <database> [--from --to]: operations and storage
  metrics for a period
- database backup list <database> [--limit]: platform-created backups
  with retention metadata
- database restore <database> --backup <id> [--source-database <db>]
  --confirm <database-id>: destructive in-place restore; status goes to
  recovering and connections/credentials are preserved
- database connection rotate <connection> --confirm <connection-id>:
  mints new credentials and prints the new one-time URL exactly once on
  stdout, matching the connection create output contract

Restore and rotate follow the exact-id --confirm convention because
they are destructive (restore overwrites data; rotate revokes the
previous credentials). All commands support --json with structured
error codes (DATABASE_BACKUPS_UNSUPPORTED, DATABASE_BACKUP_NOT_FOUND,
DATABASE_RESTORE_CONFLICT) for agent consumption.

Spec-first: command-spec.md and resource-model.md updated alongside
the implementation.

Author: AmanVarshney01

docs/product/command-spec.md

@@ -861,6 +861,91 @@ prisma-cli database create my-db --branch feature/foo --region eu-central-1
 prisma-cli database create my-db --json
 ```
 
+## `prisma-cli database usage <database> --project <id-or-name> --branch <git-name> --from <iso-date> --to <iso-date>`
+
+Purpose:
+
+- show usage metrics 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
+- `--from <iso-date>` and `--to <iso-date>` bound the reporting period; when omitted, the platform defaults the period to the current month so far
+- the CLI validates that `--from` and `--to` parse as dates and that `--from` is not after `--to` before calling the API
+- reports operations used (`ops`) and storage used (`GiB`) for the period, plus the resolved period bounds and the generation timestamp
+- read-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 usage db_123
+prisma-cli database usage acme-production --from 2026-06-01 --to 2026-06-30
+prisma-cli database usage db_123 --json
+```
+
+## `prisma-cli database backup`
+
+Manage backups for a database. `backup` is nested under `database` because
+backups exist only in the context of one Prisma Postgres database, following
+the same parent-noun/subordinate-noun/action shape as `database connection`.
+The platform creates backups automatically; the first slice is read-only.
+
+### `prisma-cli database backup list <database> --limit <n>`
+
+Purpose:
+
+- list backups 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
+- `--limit <n>` caps the number of returned backups; the platform accepts 1 to 100 and defaults to 25
+- lists backup id, type (`full` or `incremental`), status (`running`, `completed`, `failed`, or `unknown`), size when available, and created timestamp
+- includes the platform's backup retention window in days
+- read-only; never prints or returns secret values
+- fails with `DATABASE_BACKUPS_UNSUPPORTED` when the platform reports backups are not available for the database (for example remote/BYO databases)
+- fails with `DATABASE_NOT_FOUND` or `DATABASE_AMBIGUOUS` when the target cannot be selected safely
+
+Examples:
+
+```bash
+prisma-cli database backup list db_123
+prisma-cli database backup list acme-production --limit 50
+prisma-cli database backup list db_123 --json
+```
+
+## `prisma-cli database restore <database> --backup <backup-id> --source-database <database> --confirm <database-id>`
+
+Purpose:
+
+- restore a database's data from a backup
+
+Behavior:
+
+- requires auth and resolved project context; accepts `--project <id-or-name>` as an explicit fallback
+- restores into the resolved `<database>` (the target): all current data is immediately and irreversibly overwritten with the backup contents; connections and credentials are preserved, so no new connection URL is printed
+- resolves `<database>` by exact database id or exact database name inside the resolved project; `--branch <git-name>` narrows name resolution
+- `--backup <backup-id>` is required and names the backup to restore from; ids come from `database backup list`
+- by default the backup must belong to the target database; `--source-database <database>` restores from another database's backup, for example a production backup into a scratch database, and requires access to both databases' projects
+- requires `--confirm <database-id>` where the value exactly matches the resolved target database id; `--yes` does not satisfy this confirmation
+- the restore runs asynchronously: the target database status becomes `recovering` until the restore completes, and `database show` reports the current status; `nextSteps` includes the show command
+- fails with `DATABASE_RESTORE_CONFLICT` when the target database is provisioning or already recovering
+- fails with `DATABASE_NOT_FOUND` or `DATABASE_AMBIGUOUS` when a database target cannot be selected safely
+- never prints or returns connection strings, passwords, or endpoint secrets
+
+Examples:
+
+```bash
+prisma-cli database restore db_123 --backup bkp_456 --confirm db_123
+prisma-cli database restore scratch --backup bkp_456 --source-database acme-production --confirm db_789
+prisma-cli database restore db_123 --backup bkp_456 --confirm db_123 --json
+```
+
 ## `prisma-cli database remove <database> --confirm <database-id>`
 
 Purpose:
@@ -891,7 +976,8 @@ 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.
+strings are one-time-view secrets: the platform returns them only from
+`connection create` and `connection rotate`, never from read endpoints.
 
 ### `prisma-cli database connection list <database>`
 
@@ -944,6 +1030,34 @@ prisma-cli database connection create db_123 --name readonly
 prisma-cli database connection create db_123 --json
 ```
 
+### `prisma-cli database connection rotate <connection> --confirm <connection-id>`
+
+Purpose:
+
+- rotate a database connection's credentials and print the new one-time connection URL
+
+Behavior:
+
+- requires auth
+- treats `<connection>` as the connection id to rotate
+- requires `--confirm <connection-id>` where the value exactly matches the connection id; `--yes` does not satisfy this confirmation, because rotation revokes the previous credentials (best-effort) and breaks clients still using them
+- mints new credentials for the same connection; the connection id and name are unchanged
+- the new connection URL is a one-time-view secret with the same output contract as `database connection create`:
+  - in default human mode, stderr shows a short rotation summary and stdout contains exactly one line, the raw new connection URL
+  - human stderr does not repeat, label, or wrap the connection URL
+  - `--verbose` adds human-only metadata rows such as database and connection id on stderr before the URL is written to stdout
+  - `--quiet` suppresses successful stderr output and leaves stdout as exactly the raw 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
+- fails with `DATABASE_CONNECTION_NOT_FOUND` when the connection does not exist
+
+Examples:
+
+```bash
+prisma-cli database connection rotate conn_123 --confirm conn_123
+prisma-cli database connection rotate conn_123 --confirm conn_123 --json
+```
+
 ### `prisma-cli database connection remove <connection> --confirm <connection-id>`
 
 Purpose:

docs/product/resource-model.md

@@ -156,22 +156,26 @@ top-level target-context group is `branch`, not `env`.
 resource.
 
 The beta package exposes `database` as the canonical database management group.
-The first slice manages Prisma Postgres database metadata and one-time-view
+It manages Prisma Postgres database metadata, usage, backups, and one-time-view
 connection strings:
 
 - `database list`
 - `database show <database>`
 - `database create <name>`
+- `database usage <database>`
+- `database restore <database>`
 - `database remove <database>`
+- `database backup list <database>`
 - `database connection list <database>`
 - `database connection create <database>`
+- `database connection rotate <connection>`
 - `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.
+The `database connection` and `database backup` subgroups are nested because
+connections and backups exist only for databases. They follow 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 from create and rotate operations.
 
 Rules:
 
@@ -185,6 +189,13 @@ Rules:
   or return secret values
 - database and database connection removal require exact id confirmation with
   `--confirm <id>`; `--yes` is not sufficient
+- database restore and connection rotation are equally destructive (restore
+  overwrites the target's data; rotation revokes the previous credentials) and
+  require the same exact id confirmation with `--confirm <id>`
+- backups are platform-created; the CLI lists them and restores from them but
+  never creates or deletes them in the current slice
+- `database usage` and `database backup list` are read-only and never print
+  secret values
 - 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

@@ -183,5 +183,45 @@
       "createdAt": "2026-06-02T00:00:00.000Z",
       "connectionString": "postgresql://secret-production.example.prisma.io/postgres"
     }
+  ],
+  "databaseBackups": [
+    {
+      "id": "bkp_101",
+      "databaseId": "db_123",
+      "backupType": "full",
+      "status": "completed",
+      "size": 1048576,
+      "createdAt": "2026-06-20T00:00:00.000Z"
+    },
+    {
+      "id": "bkp_102",
+      "databaseId": "db_123",
+      "backupType": "incremental",
+      "status": "completed",
+      "createdAt": "2026-06-21T00:00:00.000Z"
+    },
+    {
+      "id": "bkp_201",
+      "databaseId": "db_456",
+      "backupType": "full",
+      "status": "completed",
+      "size": 5242880,
+      "createdAt": "2026-06-22T00:00:00.000Z"
+    }
+  ],
+  "databaseBackupRetentionDays": 35,
+  "databaseUsage": [
+    {
+      "databaseId": "db_123",
+      "period": {
+        "start": "2026-06-01T00:00:00.000Z",
+        "end": "2026-06-30T23:59:59.999Z"
+      },
+      "metrics": {
+        "operations": { "used": 12500, "unit": "ops" },
+        "storage": { "used": 1.25, "unit": "GiB" }
+      },
+      "generatedAt": "2026-07-01T00:00:00.000Z"
+    }
   ]
 }

packages/cli/src/adapters/mock-api.ts

@@ -69,6 +69,25 @@ interface DatabaseConnectionRecord {
   connectionString?: string;
 }
 
+interface DatabaseBackupRecord {
+  id: string;
+  databaseId: string;
+  backupType: string;
+  status: string;
+  size?: number;
+  createdAt: string;
+}
+
+interface DatabaseUsageRecord {
+  databaseId: string;
+  period: { start: string; end: string };
+  metrics: {
+    operations: { used: number; unit: string };
+    storage: { used: number; unit: string };
+  };
+  generatedAt: string;
+}
+
 interface MockApiData {
   providers: ProviderRecord[];
   users: UserRecord[];
@@ -79,6 +98,9 @@ interface MockApiData {
   deployments: DeploymentRecord[];
   databases?: DatabaseRecord[];
   databaseConnections?: DatabaseConnectionRecord[];
+  databaseBackups?: DatabaseBackupRecord[];
+  databaseUsage?: DatabaseUsageRecord[];
+  databaseBackupRetentionDays?: number;
 }
 
 export class MockApi {
@@ -317,6 +339,116 @@ export class MockApi {
     );
     return connection;
   }
+
+  getDatabaseUsage(
+    databaseId: string,
+    period?: { from?: string; to?: string },
+  ): {
+    period: { start: string; end: string };
+    metrics: {
+      operations: { used: number; unit: string };
+      storage: { used: number; unit: string };
+    };
+    generatedAt: string;
+  } {
+    const usage = (this.data.databaseUsage ?? []).find(
+      (record) => record.databaseId === databaseId,
+    );
+    const defaults = usage ?? {
+      databaseId,
+      period: {
+        start: "2026-06-01T00:00:00.000Z",
+        end: "2026-06-30T23:59:59.999Z",
+      },
+      metrics: {
+        operations: { used: 0, unit: "ops" },
+        storage: { used: 0, unit: "GiB" },
+      },
+      generatedAt: "2026-07-01T00:00:00.000Z",
+    };
+
+    return {
+      period: {
+        start: period?.from ?? defaults.period.start,
+        end: period?.to ?? defaults.period.end,
+      },
+      metrics: defaults.metrics,
+      generatedAt: defaults.generatedAt,
+    };
+  }
+
+  listDatabaseBackups(
+    databaseId: string,
+    limit?: number,
+  ): {
+    backups: Array<{
+      id: string;
+      backupType: string;
+      status: string;
+      size: number | null;
+      createdAt: string;
+    }>;
+    retentionDays: number | null;
+    hasMore: boolean;
+  } {
+    const backups = (this.data.databaseBackups ?? []).filter(
+      (backup) => backup.databaseId === databaseId,
+    );
+    const limited = limit === undefined ? backups : backups.slice(0, limit);
+
+    return {
+      backups: limited.map((backup) => ({
+        id: backup.id,
+        backupType: backup.backupType,
+        status: backup.status,
+        size: backup.size ?? null,
+        createdAt: backup.createdAt,
+      })),
+      retentionDays: this.data.databaseBackupRetentionDays ?? null,
+      hasMore: limited.length < backups.length,
+    };
+  }
+
+  restoreDatabase(input: {
+    targetDatabaseId: string;
+    sourceDatabaseId: string;
+    backupId: string;
+  }):
+    | { outcome: "restored"; database: DatabaseRecord }
+    | { outcome: "target-not-found" }
+    | { outcome: "backup-not-found" } {
+    const target = this.getDatabase(input.targetDatabaseId);
+    if (!target) {
+      return { outcome: "target-not-found" };
+    }
+
+    const backup = (this.data.databaseBackups ?? []).find(
+      (candidate) =>
+        candidate.id === input.backupId &&
+        candidate.databaseId === input.sourceDatabaseId,
+    );
+    if (!backup) {
+      return { outcome: "backup-not-found" };
+    }
+
+    target.status = "recovering";
+    return { outcome: "restored", database: target };
+  }
+
+  rotateDatabaseConnection(
+    connectionId: string,
+  ):
+    | { connection: DatabaseConnectionRecord; connectionString: string }
+    | undefined {
+    const connection = this.getDatabaseConnection(connectionId);
+    if (!connection) {
+      return undefined;
+    }
+
+    const connectionString = `postgresql://rotated-${connection.databaseId}-${connection.id}.example.prisma.io/postgres`;
+    connection.connectionString = connectionString;
+    return { connection, connectionString };
+  }
 }
 
 export type {