@canner-ca/cli 0.4.1 → 0.5.1

package/src/cli.mjs

@@ -28,7 +28,7 @@ import { randomUUID } from 'node:crypto';
 import { stdin as input, stdout as output } from 'node:process';
 import { create as tarCreate } from 'tar';
 
-const VERSION = '0.4.0';
+const VERSION = '0.5.1';
 const DEFAULT_API_BASE = 'https://api.canner.ca';
 const CONFIG_DIR = join(homedir(), '.canner');
 const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials');
@@ -151,6 +151,8 @@ async function apiRequest(creds, method, path, options = {}) {
     // fetch level. Per-call options.signal can still abort.
   };
   if (options.signal) init.signal = options.signal;
+  // A streamed request body (database imports) needs duplex: 'half' in Node's fetch.
+  if (options.duplex) init.duplex = options.duplex;
   const res = await fetch(url, init).catch((err) => {
     die(`network: ${err.message}`);
   });
@@ -161,7 +163,17 @@ async function apiRequest(creds, method, path, options = {}) {
       die("authentication failed. Your token may be revoked. Run `canner login` again.");
     }
     if (res.status === 403) {
-      die("forbidden. The API token doesn't have access to this resource.");
+      // Surface the server's specific reason: a token missing a scope
+      // (insufficient_scope) or the member's role/permission in the org
+      // (insufficient_permission) both send a human `message`.
+      const detail =
+        body?.message ||
+        (body?.error === 'insufficient_scope'
+          ? 'the API token is missing a required scope'
+          : body?.error === 'insufficient_permission'
+            ? "your role in this organization doesn't permit this action"
+            : "the API token doesn't have access to this resource");
+      die(`forbidden: ${detail}`);
     }
     const msg = body?.message || body?.error || `${res.status} ${res.statusText}`;
     die(`${method} ${path}: ${msg}`);
@@ -268,7 +280,7 @@ async function cmdLogin(_args) {
   const existing = await loadCredentials();
   const apiBase = process.env.CANNER_API_BASE || existing.apiBase || DEFAULT_API_BASE;
   info(bold('Sign in to Canner'));
-  info(`Create an API token at ${cyan(apiBase.replace('api.', '') + '/dashboard/account')}`);
+  info(`Create an API token at ${cyan(apiBase.replace('api.', '') + '/dashboard/identity/api-keys')} ${dim('(Identity → API keys)')}`);
   info(`Then paste it below. It starts with ${dim('cnr_')}`);
   const token = (await rl.question('token: ')).trim();
   rl.close();
@@ -1102,6 +1114,23 @@ function sluggify(s) {
 //   canner cmd --key=value        → { key: 'value' }
 //   canner cmd -v                 → { v: true }
 // ---------------------------------------------------------------------------
+// Flags that never take a value, so `canner db import --replace dump.dump` keeps
+// dump.dump as the positional argument instead of reading it as --replace's value.
+const BOOLEAN_FLAGS = new Set([
+  'json', 'reveal', 'sensitive', 'follow', 'dashboard', 'version', 'help',
+  'replace', 'yes', 'no-wait', 'enable', 'disable', 'restore', 'download', 'rm', 'delete', 'instance', 'pitr',
+]);
+
+// A flag repeated on the command line (e.g. `--allow a --allow b`) accumulates
+// into an array instead of the last one silently winning.
+function setArg(out, key, value) {
+  if (key in out) {
+    out[key] = Array.isArray(out[key]) ? [...out[key], value] : [out[key], value];
+  } else {
+    out[key] = value;
+  }
+}
+
 function parseArgs(argv) {
   const out = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -1109,15 +1138,15 @@ function parseArgs(argv) {
     if (a.startsWith('--')) {
       const eq = a.indexOf('=');
       if (eq !== -1) {
-        out[a.slice(2, eq)] = a.slice(eq + 1);
+        setArg(out, a.slice(2, eq), a.slice(eq + 1));
       } else {
         const key = a.slice(2);
         const next = argv[i + 1];
-        if (next && !next.startsWith('-')) {
-          out[key] = next;
+        if (next && !next.startsWith('-') && !BOOLEAN_FLAGS.has(key)) {
+          setArg(out, key, next);
           i++;
         } else {
-          out[key] = true;
+          setArg(out, key, true);
         }
       }
     } else if (a.startsWith('-') && a.length === 2) {
@@ -1129,6 +1158,1178 @@ function parseArgs(argv) {
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// canner db …                                            — project databases
+//
+//   canner db [list] [--slug X]                          list the project's databases
+//   canner db init [--pg 17|18] [--slug X]               provision the primary database
+//   canner db create <name> [--pg 17|18]                 add another database (paid plans)
+//   canner db info [<name>] [--reveal]                   connection details (password hidden by default)
+//   canner db url [<name>]                               print just the connection string
+//   canner db rm <name> --yes                            delete an additional database
+//   canner db pg-version <name> <17|18> --yes            move a database to another Postgres version
+//   canner db export [<name>] [--format custom|plain] [--out FILE]
+//   canner db import <file> [--to <name>] [--replace]    restore a pg_dump custom-format file
+//   canner db migrate-in [--to <name>] --from <url>|--from-env VAR|--from - [--replace]
+//   canner db migrate-out [--from <name>] --to-url <url>|--to-env VAR|--to-url - --yes
+//   canner db copy <from> <to> [--to-project SLUG] [--replace]
+//   canner db ops [<id>]                                 recent operations / one operation
+//
+// Long operations (export, import, migrate, copy) run on the platform: the CLI
+// starts one, then waits and shows progress. Pass --no-wait to return the
+// operation id immediately (poll with `canner db ops <id>`).
+// ---------------------------------------------------------------------------
+const DB_OP_POLL_MS = 2000;
+
+function dbBase(slug) {
+  return `/projects/${encodeURIComponent(slug)}`;
+}
+
+function fmtBytes(n) {
+  if (n == null) return '—';
+  const u = ['B', 'KB', 'MB', 'GB'];
+  let i = 0;
+  let v = Number(n);
+  while (v >= 1024 && i < u.length - 1) { v /= 1024; i++; }
+  return `${v >= 10 || i === 0 ? Math.round(v) : v.toFixed(1)} ${u[i]}`;
+}
+
+// A connection URL is a secret: never take it from a positional argument that
+// ends up in shell history unless the user insists. --from/--to-url take a URL,
+// --from-env/--to-env read an environment variable, and "-" reads one line from stdin.
+async function readSecretArg(args, urlFlag, envFlag, what) {
+  if (args[envFlag]) {
+    const v = process.env[String(args[envFlag])];
+    if (!v) die(`environment variable ${args[envFlag]} is not set.`, 2);
+    return v.trim();
+  }
+  const v = args[urlFlag];
+  if (v === '-' || v === true) {
+    const rl = createInterface({ input, output: process.stderr, terminal: false });
+    const line = await rl.question(`${what} (postgres://user:password@host:port/db): `);
+    rl.close();
+    if (!line.trim()) die(`no ${what} given.`, 2);
+    return line.trim();
+  }
+  if (typeof v === 'string' && v) return v;
+  die(`give the ${what} with --${urlFlag} <url>, --${envFlag} <VAR>, or --${urlFlag} - to type it.`, 2);
+}
+
+function requireYes(args, message) {
+  if (args.yes === true || args.y === true) return;
+  die(`${message} Re-run with --yes to confirm.`, 2);
+}
+
+async function waitForOperation(creds, base, id, args) {
+  if (args['no-wait'] === true) return null;
+  const path = `${base}/database-operations/${encodeURIComponent(id)}`;
+  let last = '';
+  for (;;) {
+    const body = await apiJSON(creds, 'GET', path);
+    const op = body?.operation;
+    if (!op) die('lost track of the operation.');
+    if (op.state === 'succeeded') {
+      if (!JSON_MODE && last) process.stderr.write('\r' + ' '.repeat(last.length) + '\r');
+      return op;
+    }
+    if (op.state === 'failed' || op.state === 'cancelled') {
+      if (!JSON_MODE && last) process.stderr.write('\r' + ' '.repeat(last.length) + '\r');
+      die(op.error || `the operation ${op.state}.`);
+    }
+    if (!JSON_MODE) {
+      const p = op.progress ?? {};
+      const bit = p.bytes != null ? ` ${fmtBytes(p.bytes)}` : p.size_mb != null ? ` ${p.size_mb} MB` : '';
+      last = `  ${op.state}…${bit}`;
+      process.stderr.write('\r' + last);
+    }
+    await new Promise((r) => setTimeout(r, DB_OP_POLL_MS));
+  }
+}
+
+async function waitForBackup(creds, base, label, id, args) {
+  if (args['no-wait'] === true) return null;
+  const path = `${base}/databases/${encodeURIComponent(label)}/backups/${encodeURIComponent(id)}`;
+  let last = '';
+  for (;;) {
+    const body = await apiJSON(creds, 'GET', path);
+    const b = body?.backup;
+    if (!b) die('lost track of the backup.');
+    if (b.state === 'succeeded') {
+      if (!JSON_MODE && last) process.stderr.write('\r' + ' '.repeat(last.length) + '\r');
+      return b;
+    }
+    if (b.state === 'failed') {
+      if (!JSON_MODE && last) process.stderr.write('\r' + ' '.repeat(last.length) + '\r');
+      die(b.error || 'the backup failed.');
+    }
+    if (!JSON_MODE) {
+      last = '  running…';
+      process.stderr.write('\r' + last);
+    }
+    await new Promise((r) => setTimeout(r, DB_OP_POLL_MS));
+  }
+}
+
+async function startAndWait(creds, base, args, method, path, body, verb) {
+  const started = await apiJSON(creds, method, path, body);
+  const op = started?.operation;
+  if (!op) die('the platform did not return an operation.');
+  if (args['no-wait'] === true) {
+    if (JSON_MODE) emitJSON(op);
+    else { info(`${green('started')} ${verb} ${dim(op.id)}`); muted(`Check it with: canner db ops ${op.id}`); }
+    return null;
+  }
+  if (!JSON_MODE) info(`${verb}…`);
+  return waitForOperation(creds, base, op.id, args);
+}
+
+async function cmdDb(args) {
+  const creds = await loadCredentials();
+  if (!creds.token) die("not signed in. Run `canner login`.");
+  const slug = await resolveSlug(args);
+  const base = dbBase(slug);
+  const sub = args._[0] ?? 'list';
+  const name = (i = 1) => args._[i] ?? 'primary';
+
+  if (sub === 'list' || sub === 'ls') {
+    const body = await apiJSON(creds, 'GET', `${base}/databases`);
+    if (JSON_MODE) return emitJSON(body);
+    const rows = body?.databases ?? [];
+    if (rows.length === 0) { muted('no database yet. Create one with `canner db init`.'); return; }
+    info(`${pad(bold('NAME'), 22)}${pad(bold('POSTGRES'), 11)}${pad(bold('SIZE'), 11)}${bold('STATUS')}`);
+    for (const d of rows) {
+      const status = d.over_quota_at ? red('write-locked (over quota)') : green('ok');
+      info(`${pad(d.is_primary ? `${d.name} ${dim('(DATABASE_URL)')}` : d.name, 22)}${pad(d.pg_version, 11)}${pad(`${d.size_mb} MB`, 11)}${status}`);
+    }
+    const l = body?.limits;
+    if (l && !l.advanced_enabled) muted('Additional databases, import and migration are available on paid plans.');
+    return;
+  }
+
+  if (sub === 'init' || sub === 'provision') {
+    const body = await apiJSON(creds, 'POST', `${base}/database`, args.pg ? { pg_version: String(args.pg) } : {});
+    if (JSON_MODE) return emitJSON(body);
+    const d = body?.database;
+    info(`${green('provisioned')} ${bold('primary')} ${dim(`(Postgres ${d?.pg_version_full ?? d?.pg_version})`)}`);
+    muted('The connection string is injected as DATABASE_URL on your next deploy.');
+    return;
+  }
+
+  if (sub === 'create' || sub === 'add') {
+    const label = args._[1];
+    if (!label) die('usage: canner db create <name> [--pg 17|18]', 2);
+    const body = await apiJSON(creds, 'POST', `${base}/databases`, {
+      name: label,
+      ...(args.pg ? { pg_version: String(args.pg) } : {}),
+      ...(args.instance === true ? { instance: true } : {}),
+    });
+    if (JSON_MODE) return emitJSON(body);
+    const d = body?.database;
+    info(`${green('created')} ${bold(label)} ${dim(`(Postgres ${d?.pg_version_full ?? d?.pg_version})`)}`);
+    muted(`Injected into your app as DATABASE_URL_${label.toUpperCase()} on your next deploy.`);
+    return;
+  }
+
+  if (sub === 'info' || sub === 'show') {
+    const body = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(name())}`);
+    const d = body?.database;
+    if (JSON_MODE) return emitJSON(args.reveal === true ? d : { ...d, password: null, connection_string: null });
+    info(`${bold(d.name)} ${dim(`Postgres ${d.pg_version_full ?? d.pg_version} · ${d.size_mb} MB`)}`);
+    info(`  user      ${d.db_user}`);
+    info(`  database  ${d.db_name}`);
+    info(`  password  ${args.reveal === true ? d.password : dim('•••••• (--reveal to show)')}`);
+    if (args.reveal === true) info(`  url       ${d.connection_string}`);
+    return;
+  }
+
+  if (sub === 'url') {
+    const body = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(name())}`);
+    const d = body?.database;
+    if (JSON_MODE) return emitJSON({ url: d.connection_string });
+    process.stdout.write(`${d.connection_string}\n`);
+    return;
+  }
+
+  if (sub === 'rm' || sub === 'delete') {
+    const label = args._[1];
+    if (!label) die('usage: canner db rm <name> --yes', 2);
+    requireYes(args, `This permanently deletes the database "${label}" and everything in it.`);
+    await apiJSON(creds, 'DELETE', `${base}/databases/${encodeURIComponent(label)}`);
+    if (JSON_MODE) return emitJSON({ ok: true, deleted: label });
+    info(`${green('deleted')} ${bold(label)}`);
+    return;
+  }
+
+  if (sub === 'pg-version') {
+    const label = args._[1];
+    const target = args._[2];
+    if (!label || !target) die('usage: canner db pg-version <name> <17|18> --yes', 2);
+    requireYes(args, 'Changing the Postgres version dumps and restores the database, with downtime while it runs.');
+    const body = await apiJSON(creds, 'PATCH', `${base}/databases/${encodeURIComponent(label)}/pg-version`, { target_version: String(target), confirm: true });
+    if (JSON_MODE) return emitJSON(body);
+    info(`${green('moved')} ${bold(label)} from Postgres ${body.from_version} to ${body.to_version}. The connection string is unchanged.`);
+    return;
+  }
+
+  if (sub === 'export') {
+    const label = name();
+    const format = args.format === 'plain' ? 'plain' : 'custom';
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(label)}/exports`, { format }, 'exporting');
+    if (!done) return;
+    const out = resolve(typeof args.out === 'string' ? args.out : done.result.file_name);
+    const res = await apiRequest(creds, 'GET', `${base}/database-operations/${encodeURIComponent(done.id)}/download`);
+    const { Readable } = await import('node:stream');
+    const { pipeline } = await import('node:stream/promises');
+    const { createWriteStream } = await import('node:fs');
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(out, { mode: 0o600 }));
+    if (JSON_MODE) return emitJSON({ file: out, bytes: done.result.bytes, sha256: done.result.sha256, format });
+    info(`${green('exported')} ${bold(label)} → ${cyan(out)} ${dim(`(${fmtBytes(done.result.bytes)}, sha256 ${done.result.sha256.slice(0, 12)}…)`)}`);
+    muted(`Restore with: ${done.result.restore_hint}`);
+    return;
+  }
+
+  if (sub === 'import') {
+    const file = args._[1];
+    if (!file) die('usage: canner db import <file.dump> [--to <name>] [--replace]', 2);
+    const to = typeof args.to === 'string' ? args.to : 'primary';
+    const size = (await stat(resolve(file))).size;
+    const { createReadStream } = await import('node:fs');
+    if (!JSON_MODE) info(`uploading ${basename(file)} (${fmtBytes(size)})…`);
+    const res = await apiRequest(creds, 'POST',
+      `${base}/databases/${encodeURIComponent(to)}/imports${args.replace === true ? '?replace=true' : ''}`,
+      { headers: { 'Content-Type': 'application/octet-stream', 'Content-Length': String(size) }, body: createReadStream(resolve(file)), duplex: 'half' });
+    const started = await res.json();
+    const opId = started?.operation?.id;
+    if (args['no-wait'] === true) {
+      if (JSON_MODE) return emitJSON(started.operation);
+      info(`${green('started')} import ${dim(opId)}`);
+      return;
+    }
+    if (!JSON_MODE) info('restoring…');
+    const done = await waitForOperation(creds, base, opId, args);
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('imported')} into ${bold(to)}`);
+    if (done.result?.snapshot) muted(`A snapshot of the previous contents was kept for 7 days (${fmtBytes(done.result.snapshot.bytes)}).`);
+    return;
+  }
+
+  if (sub === 'migrate-in') {
+    const to = typeof args.to === 'string' ? args.to : 'primary';
+    const url = await readSecretArg(args, 'from', 'from-env', 'source connection URL');
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(to)}/migrate-in`,
+      { url, replace: args.replace === true }, 'migrating in');
+    if (!done) return;
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('migrated')} ${dim(done.result?.source_host ?? '')} → ${bold(to)}`);
+    return;
+  }
+
+  if (sub === 'migrate-out') {
+    const from = typeof args.from === 'string' ? args.from : 'primary';
+    requireYes(args, 'This writes this database into the server you name.');
+    const url = await readSecretArg(args, 'to-url', 'to-env', 'target connection URL');
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(from)}/migrate-out`,
+      { url, replace: args.replace === true, confirm: true }, 'migrating out');
+    if (!done) return;
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('migrated')} ${bold(from)} → ${dim(done.result?.target_host ?? '')}`);
+    return;
+  }
+
+  if (sub === 'copy') {
+    const from = args._[1];
+    const to = args._[2];
+    if (!from || !to) die('usage: canner db copy <from> <to> [--to-project SLUG] [--replace]', 2);
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(from)}/copy`,
+      { target_name: to, ...(args['to-project'] ? { target_project: String(args['to-project']) } : {}), replace: args.replace === true }, 'copying');
+    if (!done) return;
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('copied')} ${bold(from)} → ${bold(to)}`);
+    return;
+  }
+
+  if (sub === 'ops' || sub === 'operations') {
+    const id = args._[1];
+    if (id) {
+      const body = await apiJSON(creds, 'GET', `${base}/database-operations/${encodeURIComponent(id)}`);
+      if (JSON_MODE) return emitJSON(body.operation);
+      const o = body.operation;
+      info(`${bold(o.kind)} ${dim(o.id)}  ${o.state === 'succeeded' ? green(o.state) : o.state === 'failed' ? red(o.state) : yellow(o.state)}`);
+      if (o.error) info(`  ${red(o.error)}`);
+      if (o.progress?.bytes != null) info(`  ${fmtBytes(o.progress.bytes)} written`);
+      if (o.progress?.size_mb != null) info(`  target is ${o.progress.size_mb} MB`);
+      return;
+    }
+    const body = await apiJSON(creds, 'GET', `${base}/database-operations`);
+    const rows = body?.operations ?? [];
+    if (JSON_MODE) return emitJSON(rows);
+    if (rows.length === 0) { muted('no database operations yet.'); return; }
+    info(`${pad(bold('ID'), 12)}${pad(bold('KIND'), 14)}${pad(bold('STATE'), 12)}${bold('WHEN')}`);
+    for (const o of rows) {
+      info(`${pad(o.id.slice(0, 8), 12)}${pad(o.kind, 14)}${pad(o.state === 'succeeded' ? green(o.state) : o.state === 'failed' ? red(o.state) : yellow(o.state), 12)}${dim(relTime(o.created_at))}`);
+    }
+    return;
+  }
+
+  if (sub === 'external' || sub === 'external-access') {
+    const label = args._[1] ?? 'primary';
+    const path = `${base}/databases/${encodeURIComponent(label)}/external-access`;
+
+    if (args.disable === true) {
+      const body = await apiJSON(creds, 'PATCH', path, { enabled: false });
+      if (JSON_MODE) return emitJSON(body.external_access);
+      info(`${green('disabled')} external access on ${bold(label)}`);
+      return;
+    }
+    if (args.enable === true || args.allow !== undefined || args['allow-all'] === true) {
+      const allowlist = args.allow === undefined ? [] : (Array.isArray(args.allow) ? args.allow : [args.allow]).map(String);
+      if (args['allow-all'] === true) {
+        requireYes(args, 'This allows connections to this database from anywhere on the internet.');
+        allowlist.push('0.0.0.0/0', '::/0');
+      }
+      if (allowlist.length === 0) die('give at least one --allow <cidr>, or --allow-all --yes.', 2);
+      const body = await apiJSON(creds, 'PATCH', path, { enabled: true, allowlist, allow_open: args['allow-all'] === true });
+      if (JSON_MODE) return emitJSON(body.external_access);
+      const ea = body.external_access;
+      info(`${green('enabled')} external access on ${bold(label)}`);
+      info(`  ${ea.host}:${ea.port}`);
+      info(`  allowed: ${ea.allowlist.join(', ')}`);
+      return;
+    }
+    // No mutating flag: show current status.
+    const body = await apiJSON(creds, 'GET', path);
+    const ea = body.external_access;
+    if (JSON_MODE) return emitJSON(ea);
+    info(`${bold(label)}  ${ea.enabled ? green('enabled') : dim('disabled')}`);
+    info(`  ${ea.host}:${ea.port}${!ea.configured ? dim('  (not available on this platform instance yet)') : ''}`);
+    if (ea.enabled) info(`  allowed: ${ea.allowlist.length ? ea.allowlist.join(', ') : dim('(none)')}`);
+    return;
+  }
+
+  if (sub === 'rotate' || sub === 'rotate-credentials') {
+    const label = args._[1] ?? 'primary';
+    requireYes(args, 'This changes the password — your app needs the new DATABASE_URL from the next deploy.');
+    const body = await apiJSON(creds, 'POST', `${base}/databases/${encodeURIComponent(label)}/rotate-credentials`);
+    if (JSON_MODE) return emitJSON(body.database);
+    info(`${green('rotated')} the password for ${bold(label)}.`);
+    muted('Redeploy to pick up the new DATABASE_URL.');
+    return;
+  }
+
+  if (sub === 'backup-policy') {
+    const label = args._[1] ?? 'primary';
+    const path = `${base}/databases/${encodeURIComponent(label)}/backup-policy`;
+
+    if (args.disable === true) {
+      const body = await apiJSON(creds, 'PATCH', path, { enabled: false });
+      if (JSON_MODE) return emitJSON(body.policy);
+      info(`${green('disabled')} scheduled backups on ${bold(label)}`);
+      return;
+    }
+    const setting = args.enable === true || args.every !== undefined || args.keep !== undefined || args['keep-count'] !== undefined || args.offsite !== undefined;
+    if (setting) {
+      const patch = {};
+      if (args.enable === true) patch.enabled = true;
+      if (args.every !== undefined) patch.interval_hours = Number(args.every);
+      if (args.keep !== undefined) patch.retention_days = Number(args.keep);
+      if (args['keep-count'] !== undefined) patch.retention_count = args['keep-count'] === 'none' ? null : Number(args['keep-count']);
+      if (args.offsite !== undefined) {
+        if (args.offsite === 'off' || args.offsite === 'none') patch.offsite_destination_id = null;
+        else if (typeof args.offsite === 'string' && args.offsite !== 'on') {
+          const all = (await apiJSON(creds, 'GET', `${base}/backup-destinations`)).destinations;
+          const hit = all.find((d) => d.id === args.offsite || d.name.toLowerCase() === args.offsite.toLowerCase());
+          if (!hit) die(`no destination "${args.offsite}". List them with: canner db offsite`, 1);
+          patch.offsite_destination_id = hit.id;
+        } else die('--offsite takes a destination name (see: canner db offsite) or off.', 2);
+      }
+      const body = await apiJSON(creds, 'PATCH', path, patch);
+      if (JSON_MODE) return emitJSON(body.policy);
+      const p = body.policy;
+      info(`${green('set')} backup policy for ${bold(label)}: every ${p.interval_hours}h, keep ${p.retention_days}d${p.retention_count ? ` (max ${p.retention_count})` : ''}`);
+      return;
+    }
+    const body = await apiJSON(creds, 'GET', path);
+    const p = body.policy;
+    if (JSON_MODE) return emitJSON(p);
+    info(`${bold(label)}  ${p.enabled ? green('enabled') : dim('disabled')}`);
+    info(`  every ${p.interval_hours}h, keep ${p.retention_days}d${p.retention_count ? `, max ${p.retention_count} backups` : ''}`);
+    info(`  off-site copy ${p.offsite ? green('on') : dim('off')}`);
+    if (p.enabled && p.next_run_at) info(`  next run ${dim(relTime(p.next_run_at))}`);
+    return;
+  }
+
+  if (sub === 'backup') {
+    const label = name();
+    const started = await apiJSON(creds, 'POST', `${base}/databases/${encodeURIComponent(label)}/backups`);
+    const b = started?.backup;
+    if (!b) die('the platform did not return a backup.');
+    if (args['no-wait'] === true) {
+      if (JSON_MODE) return emitJSON(b);
+      info(`${green('started')} backup ${dim(b.id)}`);
+      muted(`Check it with: canner db backups ${label} ${b.id}`);
+      return;
+    }
+    if (!JSON_MODE) info('backing up…');
+    const done = await waitForBackup(creds, base, label, b.id, args);
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('backed up')} ${bold(label)} ${dim(`(${fmtBytes(done.bytes)}, sha256 ${done.sha256.slice(0, 12)}…)`)}`);
+    return;
+  }
+
+  if (sub === 'backups') {
+    const label = args._[1] ?? 'primary';
+    const id = args._[2];
+    const listPath = `${base}/databases/${encodeURIComponent(label)}/backups`;
+
+    if (!id) {
+      const body = await apiJSON(creds, 'GET', listPath);
+      const rows = body?.backups ?? [];
+      if (JSON_MODE) return emitJSON(rows);
+      if (rows.length === 0) { muted(`no backups yet for ${label}. Create one with \`canner db backup ${label}\`.`); return; }
+      info(`${pad(bold('ID'), 12)}${pad(bold('KIND'), 11)}${pad(bold('STATE'), 12)}${pad(bold('SIZE'), 11)}${bold('WHEN')}`);
+      for (const b of rows) {
+        const state = b.state === 'succeeded' ? green(b.state) : b.state === 'failed' ? red(b.state) : yellow(b.state);
+        info(`${pad(b.id.slice(0, 8), 12)}${pad(b.kind, 11)}${pad(state, 12)}${pad(b.bytes != null ? fmtBytes(b.bytes) : '—', 11)}${dim(relTime(b.created_at))}`);
+      }
+      return;
+    }
+
+    const itemPath = `${listPath}/${encodeURIComponent(id)}`;
+
+    if (args.rm === true || args.delete === true) {
+      requireYes(args, 'This permanently deletes the backup — its encryption key is destroyed immediately, so this cannot be undone.');
+      await apiJSON(creds, 'DELETE', itemPath);
+      if (JSON_MODE) return emitJSON({ ok: true, deleted: id });
+      info(`${green('deleted')} backup ${dim(id.slice(0, 8))}`);
+      return;
+    }
+
+    if (args.restore === true) {
+      const to = typeof args.to === 'string' ? args.to : undefined;
+      if (to) requireYes(args, `This replaces the contents of "${to}" with this backup (Canner takes a snapshot first).`);
+      const inspect = args.inspect === true;
+      if (inspect && to) die('--inspect restores into a new temporary database; it cannot be combined with --to.', 2);
+      const body = await apiJSON(creds, 'POST', `${itemPath}/restore`, to ? { target_name: to, confirm: true } : inspect ? { inspect: true } : {});
+      const opId = body?.operation_id;
+      if (args['no-wait'] === true) {
+        if (JSON_MODE) return emitJSON(body);
+        info(`${green('started')} restore ${dim(opId)} → ${bold(body.database.name)}`);
+        muted(`Check it with: canner db ops ${opId}`);
+        return;
+      }
+      if (!JSON_MODE) info('restoring…');
+      const done = await waitForOperation(creds, base, opId, args);
+      if (JSON_MODE) return emitJSON({ ...done, database: body.database });
+      info(`${green('restored')} into ${bold(body.database.name)}`);
+      if (inspect) muted(`Temporary inspect database (deleted ${dim(relTime(body.inspect_expires_at))}). Compare it: canner db diff ${body.database.name}. Keep it: canner db inspect ${body.database.name} --keep`);
+      return;
+    }
+
+    if (args.offsite !== undefined) {
+      const body = {};
+      if (typeof args.offsite === 'string') {
+        const all = (await apiJSON(creds, 'GET', `${base}/backup-destinations`)).destinations;
+        const hit = all.find((d) => d.id === args.offsite || d.name.toLowerCase() === args.offsite.toLowerCase());
+        if (!hit) die(`no destination "${args.offsite}". List them with: canner db offsite`, 1);
+        body.destination_id = hit.id;
+      }
+      await apiJSON(creds, 'POST', `${itemPath}/offsite`, body);
+      if (JSON_MODE) return emitJSON({ ok: true });
+      info(`${green('copied')} backup ${dim(id.slice(0, 8))} to your off-site bucket`);
+      return;
+    }
+
+    if (args.verify === true) {
+      const body = await apiJSON(creds, 'POST', `${itemPath}/verify`);
+      const opId = body?.operation_id;
+      if (args['no-wait'] === true) {
+        if (JSON_MODE) return emitJSON(body);
+        info(`${green('started')} test restore ${dim(opId)}`);
+        return;
+      }
+      if (!JSON_MODE) info('test-restoring…');
+      const done = await waitForOperation(creds, base, opId, args);
+      if (JSON_MODE) return emitJSON(done);
+      info(`${green('verified')} backup ${dim(id.slice(0, 8))}: ${done?.result?.tables ?? '?'} tables restored and readable`);
+      return;
+    }
+
+    if (args.download === true) {
+      const out = resolve(typeof args.out === 'string' ? args.out : `${label}-${id.slice(0, 8)}.dump`);
+      const res = await apiRequest(creds, 'GET', `${itemPath}/download`);
+      const { Readable } = await import('node:stream');
+      const { pipeline } = await import('node:stream/promises');
+      const { createWriteStream } = await import('node:fs');
+      await pipeline(Readable.fromWeb(res.body), createWriteStream(out, { mode: 0o600 }));
+      if (JSON_MODE) return emitJSON({ file: out });
+      info(`${green('downloaded')} → ${cyan(out)}`);
+      return;
+    }
+
+    const body = await apiJSON(creds, 'GET', itemPath);
+    const b = body?.backup;
+    if (JSON_MODE) return emitJSON(b);
+    info(`${bold(b.id)} ${dim(b.kind)}  ${b.state === 'succeeded' ? green(b.state) : b.state === 'failed' ? red(b.state) : yellow(b.state)}`);
+    if (b.error) info(`  ${red(b.error)}`);
+    if (b.bytes != null) info(`  ${fmtBytes(b.bytes)}`);
+    if (b.expires_at) info(`  expires ${dim(relTime(b.expires_at))}`);
+    return;
+  }
+
+  if (sub === 'diff') {
+    const label = args._[1];
+    if (!label) die('usage: canner db diff <name> [--against <name>]', 2);
+    const q = typeof args.against === 'string' ? `?against=${encodeURIComponent(args.against)}` : '';
+    const d = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(label)}/diff${q}`);
+    if (JSON_MODE) return emitJSON(d);
+    info(`${bold(d.to)} compared with ${bold(d.from)}: ${d.summary.added} only in ${d.to}, ${d.summary.removed} missing, ${d.summary.changed} different, ${d.summary.same} same`);
+    for (const t of d.tables.filter((x) => x.status !== 'same')) {
+      const tag = t.status === 'added' ? green('added  ') : t.status === 'removed' ? red('missing') : yellow('changed');
+      info(`  ${tag} ${pad(t.table, 32)} ${dim(`${t.rows_from ?? '?'} → ${t.rows_to ?? '?'} rows`)}`);
+    }
+    return;
+  }
+
+  if (sub === 'inspect') {
+    const label = args._[1];
+    if (!label) die('usage: canner db inspect <name> --keep | --extend HOURS', 2);
+    const body = args.keep === true ? { keep: true } : args.extend !== undefined ? { hours: Number(args.extend) } : null;
+    if (!body) die('use --keep to make it permanent, or --extend HOURS to push the expiry out.', 2);
+    await apiJSON(creds, 'PATCH', `${base}/databases/${encodeURIComponent(label)}/inspect`, body);
+    if (JSON_MODE) return emitJSON({ ok: true });
+    info(`${green('updated')} ${bold(label)}`);
+    return;
+  }
+
+  if (sub === 'resources') {
+    const path = `${base}/instance/resources`;
+    const action = args._[1];
+    const mb = (n) => (n >= 1024 ? `${(n / 1024).toFixed(n % 1024 === 0 ? 0 : 1)} GB` : `${n} MB`);
+    if (action === 'apply') {
+      requireYes(args, 'Applying restarts your dedicated instance; connections drop for a few seconds.');
+      const r = await apiJSON(creds, 'POST', `${path}/apply`, { confirm: true });
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('applied')} the memory budget${r.limits_applied ? '' : yellow(' (hard limit pending on the host)')}`);
+      if (r.redeploy_recommended) muted('Your app memory limit was lowered to its new ceiling. Redeploy the app to use it.');
+      return;
+    }
+    if (action === 'set') {
+      const patch = {};
+      if (args.share !== undefined) patch.pg_share_pct = Number(args.share);
+      if (args['app-reserved'] !== undefined) {
+        const cur = (await apiJSON(creds, 'GET', path)).resources.budget;
+        patch.reserved_to_pg_mb = cur.reserved_purchased_mb - Math.round(Number(args['app-reserved']) * 1024);
+      }
+      if (Object.keys(patch).length === 0) die('nothing to change. Use --share PCT (10-90) or --app-reserved GB.', 2);
+      const r = await apiJSON(creds, 'PATCH', path, patch);
+      if (JSON_MODE) return emitJSON(r.resources);
+      info(`${green('saved')} the split. It takes effect with: canner db resources apply --yes`);
+      return;
+    }
+    const r = (await apiJSON(creds, 'GET', path)).resources;
+    if (JSON_MODE) return emitJSON(r);
+    const b = r.budget;
+    info(`${bold('postgres')}  ${mb(b.pg.total_mb)}  (${mb(b.pg.reserved_mb)} guaranteed, ${mb(b.pg.pooled_mb)} shared)`);
+    info(`${bold('app')}       ${mb(b.app.ceiling_mb)}  (${mb(b.app.reserved_mb)} guaranteed, ${mb(b.app.pooled_mb)} shared)`);
+    info(`  Postgres takes ${b.pg_share_pct}% of the shared memory; reserved RAM bought: ${mb(b.reserved_purchased_mb)} (+ ${mb(b.reserved_included_mb)} included)`);
+    info(`  ${r.applied ? `in force: ${mb(r.applied.max_mb)} limit, ${dim(relTime(r.applied.at))}` : 'not applied yet'}${r.pending ? yellow('  (changes pending: canner db resources apply --yes)') : ''}`);
+    if (r.applied?.error) info(`  ${yellow(r.applied.error)}`);
+    return;
+  }
+
+  if (sub === 'extensions') {
+    const label = args._[1] ?? 'primary';
+    const action = args._[2];
+    const path = `${base}/databases/${encodeURIComponent(label)}/extensions`;
+    if (action === 'install') {
+      const name = args._[3];
+      if (!name) die('usage: canner db extensions <db> install <extension> [--window] [--yes]', 2);
+      const needsRestart = name === 'pg_cron';
+      if (needsRestart) requireYes(args, `${name} loads a library at startup: installing it restarts your instance${args.window === true ? ' in the next maintenance window' : ' now; connections drop for a few seconds'}.`);
+      const r = await apiJSON(creds, 'POST', path, { extension: name, when: args.window === true ? 'window' : 'now', confirm: needsRestart ? true : undefined });
+      if (JSON_MODE) return emitJSON(r);
+      if (r.restart && !r.restart.restarted) info(`${yellow('scheduled')} ${bold(name)}: the instance restarts at the next maintenance window (${r.restart.scheduled_for ?? 'unknown'}) and installs it then.`);
+      else info(`${green('installed')} ${bold(name)}`);
+      return;
+    }
+    if (action === 'update') {
+      const name = args._[3];
+      if (!name) die('usage: canner db extensions <db> update <extension>', 2);
+      const r = await apiJSON(creds, 'POST', `${path}/${encodeURIComponent(name)}/update`);
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('updated')} ${bold(name)}`);
+      return;
+    }
+    if (action === 'rm') {
+      const name = args._[3];
+      if (!name) die('usage: canner db extensions <db> rm <extension> --yes', 2);
+      requireYes(args, `This removes ${name} from the database. Nothing is removed if objects still use it.`);
+      const r = await apiJSON(creds, 'DELETE', `${path}/${encodeURIComponent(name)}`);
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('removed')} ${bold(name)}${r.restart_pending ? dim('  (the library stops loading at the next restart)') : ''}`);
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r);
+    for (const e of r.extensions) {
+      const state = e.installed_version ? green(`installed ${e.installed_version}`) : e.available ? dim('available') : red('unavailable');
+      info(`${pad(bold(e.id), 24)}${pad(state, 24)}${e.update_available ? yellow(`update to ${e.default_version}  `) : ''}${dim(e.description)}${e.preload ? dim('  (restarts the instance)') : ''}`);
+    }
+    if (r.pg_cron_database) muted(`pg_cron runs in the database "${r.pg_cron_database}".`);
+    return;
+  }
+
+  if (sub === 'tuning') {
+    const path = `${base}/instance/config`;
+    const patch = {};
+    if (typeof args.preset === 'string') patch.preset = args.preset.replace(/-/g, '_');
+    const ov = {};
+    if (args['statement-timeout'] !== undefined) ov.statement_timeout_ms = Math.round(Number(args['statement-timeout']) * 1000);
+    if (args['idle-timeout'] !== undefined) ov.idle_in_transaction_timeout_ms = Math.round(Number(args['idle-timeout']) * 1000);
+    if (args['lock-timeout'] !== undefined) ov.lock_timeout_ms = Math.round(Number(args['lock-timeout']) * 1000);
+    if (Object.keys(ov).length > 0) {
+      const cur = (await apiJSON(creds, 'GET', path)).config.overrides;
+      patch.overrides = { ...cur, ...ov };
+    }
+    if (args['window-day'] !== undefined || args['window-hour'] !== undefined || args['window-tz'] !== undefined) {
+      const cur = (await apiJSON(creds, 'GET', path)).config.window;
+      patch.window = {
+        day: args['window-day'] === undefined ? cur.day : args['window-day'] === 'all' ? null : Number(args['window-day']),
+        hour: args['window-hour'] === undefined ? cur.hour : Number(args['window-hour']),
+        tz: typeof args['window-tz'] === 'string' ? args['window-tz'] : cur.tz,
+      };
+    }
+    const r = Object.keys(patch).length > 0 ? await apiJSON(creds, 'PATCH', path, patch) : await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r.config);
+    const c = r.config;
+    if (Object.keys(patch).length > 0) info(`${green('saved')}. No restart needed.`);
+    const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+    const secs = (ms) => (ms ? `${ms / 1000} s` : 'none');
+    info(`${bold('preset')}   ${c.preset}  ${dim(`(${c.presets.join(' | ')})`)}`);
+    info(`${bold('timeouts')} statement ${secs(c.overrides.statement_timeout_ms)}, idle in transaction ${secs(c.overrides.idle_in_transaction_timeout_ms)}, lock wait ${secs(c.overrides.lock_timeout_ms)}`);
+    info(`${bold('window')}   ${c.window.day === null ? 'every day' : days[c.window.day]} ${String(c.window.hour).padStart(2, '0')}:00 for two hours, ${c.window.tz}${c.window_open ? green('  (open now)') : c.next_window ? dim(`  (next ${relTime(c.next_window)})`) : ''}`);
+    if (c.restart.waiting_for_window) info(yellow(`  a restart is waiting for the window; do it now with: canner db restart --yes`));
+    if (c.restart.settings.length > 0) info(yellow(`  waiting for a restart: ${c.restart.settings.join(', ')}`));
+    return;
+  }
+
+  if (sub === 'restart') {
+    requireYes(args, 'Restarting your dedicated instance drops connections for a few seconds.');
+    const r = await apiJSON(creds, 'POST', `${base}/instance/restart`, { confirm: true });
+    if (JSON_MODE) return emitJSON(r);
+    info(`${green('restarted')} the instance${r.failed_actions ? yellow(` (${r.failed_actions} queued action(s) failed)`) : ''}`);
+    return;
+  }
+
+  if (sub === 'replication') {
+    const label = args._[1] ?? 'primary';
+    const action = args._[2];
+    const path = `${base}/databases/${encodeURIComponent(label)}/replication`;
+    const inst = `${base}/instance/replication`;
+    if (action === 'on') {
+      requireYes(args, `Turning logical replication on restarts your instance${args.window === true ? ' in the next maintenance window' : ' now; connections drop for a few seconds'}.`);
+      const body = { enabled: true, when: args.window === true ? 'window' : 'now', confirm: true };
+      if (args.cap !== undefined) body.cap_mb = Number(args.cap);
+      const r = await apiJSON(creds, 'POST', inst, body);
+      if (JSON_MODE) return emitJSON(r);
+      info(r.restart && !r.restart.restarted ? `${yellow('scheduled')}: the instance restarts at the next maintenance window (${r.restart.scheduled_for ?? 'unknown'}).` : `${green('on')} logical replication`);
+      muted(`Next: create a login with \`canner db roles ${label} create <name> --replication\` and a publication with \`canner db replication ${label} pub <name> --all\`.`);
+      return;
+    }
+    if (action === 'off') {
+      requireYes(args, 'Turning logical replication off restarts your instance for a few seconds. Remove every slot and replication role first.');
+      const r = await apiJSON(creds, 'POST', inst, { enabled: false, when: args.window === true ? 'window' : 'now', confirm: true });
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('off')} logical replication`);
+      return;
+    }
+    if (action === 'cap') {
+      const mb = Number(args._[3]);
+      if (!Number.isFinite(mb)) die('usage: canner db replication <db> cap <MB>', 2);
+      const r = await apiJSON(creds, 'PATCH', inst, { cap_mb: mb });
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('set')} the limit on WAL held back per slot to ${mb} MB (no restart)`);
+      return;
+    }
+    if (action === 'pub') {
+      const name = args._[3];
+      if (!name) die('usage: canner db replication <db> pub <name> --all | --tables schema.table,schema.table', 2);
+      const body = args.all === true ? { name, all_tables: true } : { name, tables: String(args.tables ?? '').split(',').map((x) => x.trim()).filter(Boolean) };
+      if (args.all !== true && body.tables.length === 0) die('give --all or --tables schema.table,schema.table.', 2);
+      const r = await apiJSON(creds, 'POST', `${path}/publications`, body);
+      if (JSON_MODE) return emitJSON(r.replication);
+      info(`${green('created')} publication ${bold(name)}`);
+      return;
+    }
+    if (action === 'unpub' || action === 'drop-slot') {
+      const name = args._[3];
+      if (!name) die(`usage: canner db replication <db> ${action} <name> --yes`, 2);
+      requireYes(args, action === 'unpub' ? `This drops the publication "${name}"; subscribers that use it stop receiving changes.` : `This drops the slot "${name}" and disconnects its subscriber, which cannot resume.`);
+      const r = await apiJSON(creds, 'DELETE', `${path}/${action === 'unpub' ? 'publications' : 'slots'}/${encodeURIComponent(name)}`);
+      if (JSON_MODE) return emitJSON(r.replication);
+      info(`${green('dropped')} ${action === 'unpub' ? 'publication' : 'slot'} ${bold(name)}`);
+      return;
+    }
+    const r = (await apiJSON(creds, 'GET', path)).replication;
+    if (JSON_MODE) return emitJSON(r);
+    info(`logical replication ${r.active ? green('on') : r.enabled ? yellow('saved, waiting for a restart') : dim('off')}  ${dim(`(limit ${r.cap_mb} MB of WAL per slot)`)}`);
+    for (const p of r.publications) info(`  publication ${bold(p.name)}  ${dim(p.all_tables ? 'all tables' : p.tables.join(', '))}`);
+    for (const x of r.slots) {
+      const tone = x.health === 'ok' ? green : x.health === 'lost' || x.health === 'critical' ? red : yellow;
+      info(`  slot ${bold(x.slot_name)}  ${tone(x.health)}  ${dim(`${x.retained_mb} MB held back (${x.percent_of_cap}% of the limit)`)}`);
+    }
+    return;
+  }
+
+  if (sub === 'subscriptions') {
+    const label = args._[1] ?? 'primary';
+    const action = args._[2];
+    const path = `${base}/databases/${encodeURIComponent(label)}/subscriptions`;
+    if (action === 'add') {
+      const name = args._[3];
+      if (!name || typeof args.publication !== 'string') die('usage: canner db subscriptions <db> add <name> --from <url>|--from-env VAR|--from - --publication p1,p2 [--no-copy]', 2);
+      const url = await readSecretArg(args, 'from', 'from-env', 'connection URL of the server to follow');
+      const body = { name, url, publications: args.publication.split(',').map((x) => x.trim()).filter(Boolean), copy_data: args['no-copy'] !== true };
+      const r = await apiJSON(creds, 'POST', path, body);
+      if (JSON_MODE) return emitJSON(r.subscription);
+      info(`${green('following')} ${bold(r.subscription.publications.join(', '))} on ${r.subscription.host}:${r.subscription.port}/${r.subscription.remote_db} as ${bold(name)}`);
+      muted(`The existing rows are copied first. Watch it with: canner db subscriptions ${label}`);
+      return;
+    }
+    if (action === 'refresh' || action === 'pause' || action === 'resume') {
+      const name = args._[3];
+      if (!name) die(`usage: canner db subscriptions <db> ${action} <name>`, 2);
+      const r = action === 'refresh'
+        ? await apiJSON(creds, 'POST', `${path}/${encodeURIComponent(name)}/refresh`)
+        : await apiJSON(creds, 'PATCH', `${path}/${encodeURIComponent(name)}`, { enabled: action === 'resume' });
+      if (JSON_MODE) return emitJSON(r.subscriptions);
+      info(`${green(action === 'refresh' ? 'refreshed' : action === 'pause' ? 'paused' : 'resumed')} ${bold(name)}`);
+      return;
+    }
+    if (action === 'rm') {
+      const name = args._[3];
+      if (!name) die('usage: canner db subscriptions <db> rm <name> [--force] --yes', 2);
+      requireYes(args, `This stops following with "${name}" and removes its replication slot on the other server. Rows already copied stay.`);
+      await apiJSON(creds, 'DELETE', `${path}/${encodeURIComponent(name)}${args.force === true ? '?force=true' : ''}`);
+      if (JSON_MODE) return emitJSON({ ok: true, removed: name });
+      info(`${green('stopped')} following with ${bold(name)}`);
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r);
+    if (r.subscriptions.length === 0) { muted(`not following any server. Start with: canner db subscriptions ${label} add <name> --from-env URL_VAR --publication <name>`); return; }
+    for (const x of r.subscriptions) {
+      const tone = x.health === 'streaming' ? green : x.health === 'error' ? red : x.health === 'disabled' ? yellow : cyan;
+      info(`${pad(bold(x.name), 22)}${tone(x.health)}  ${dim(`${x.remote_user}@${x.host}:${x.port}/${x.remote_db}  ${x.publications.join(',')}`)}`);
+      info(`  ${x.tables_ready}/${x.tables_total} tables in step${x.last_message_at ? `, last change ${relTime(x.last_message_at)}` : ''}${x.apply_errors ? red(`, ${x.apply_errors} error(s)`) : ''}`);
+    }
+    return;
+  }
+
+  if (sub === 'metrics') {
+    const label = args._[1] ?? 'primary';
+    const range = typeof args.range === 'string' ? args.range : '24h';
+    const m = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(label)}/metrics?range=${encodeURIComponent(range)}`);
+    if (JSON_MODE) return emitJSON(m);
+    const pts = m.database.points;
+    if (m.database.samples === 0) { muted('no samples yet: metrics appear a few minutes after a database is created.'); return; }
+    const tx = pts.reduce((n, p) => n + p.transactions, 0);
+    const conns = pts.map((p) => p.connections).filter((v) => v !== null);
+    const hits = pts.map((p) => p.cache_hit).filter((v) => v !== null);
+    info(`${bold(label)}  last ${range}`);
+    info(`  transactions   ${tx.toLocaleString()}  (${pts.reduce((n, p) => n + p.rollbacks, 0).toLocaleString()} rolled back)`);
+    info(`  connections    peak ${conns.length ? Math.max(...conns) : '—'}`);
+    info(`  cache hit      ${hits.length ? (100 * hits.reduce((a, b) => a + b, 0) / hits.length).toFixed(1) + '%' : '—'}`);
+    const last = [...pts].reverse().find((p) => p.size_bytes !== null);
+    if (last) info(`  size           ${fmtBytes(last.size_bytes)}`);
+    if (m.instance) {
+      const ip = m.instance.points;
+      const mem = ip.map((p) => p.mem_current).filter((v) => v !== null);
+      const cpu = ip.map((p) => p.cpu_cores).filter((v) => v !== null);
+      info(`  instance       memory peak ${mem.length ? fmtBytes(Math.max(...mem)) : '—'}, cpu peak ${cpu.length ? Math.max(...cpu).toFixed(2) + ' cores' : '—'}`);
+    }
+    return;
+  }
+
+  if (sub === 'monitoring') {
+    const path = `${base}/instance/monitoring`;
+    const action = args._[1];
+    if (action === 'on' || action === 'off') {
+      const on = action === 'on';
+      requireYes(args, on ? 'Turning monitoring on restarts your instance; connections drop for a few seconds.' : 'Turning monitoring off removes query statistics and logs and restarts your instance for a few seconds.');
+      const body = { enabled: on, confirm: true };
+      if (args['slow-ms'] !== undefined) body.slow_ms = Number(args['slow-ms']);
+      const r = await apiJSON(creds, 'POST', path, body);
+      if (JSON_MODE) return emitJSON(r.monitoring);
+      info(`${green(on ? 'on' : 'off')} query insights and logs${on ? `, logging statements slower than ${r.monitoring.slow_ms} ms` : ''}`);
+      return;
+    }
+    if (args['slow-ms'] !== undefined) {
+      const r = await apiJSON(creds, 'POST', path, { enabled: true, slow_ms: Number(args['slow-ms']) });
+      if (JSON_MODE) return emitJSON(r.monitoring);
+      info(`${green('set')} slow-query threshold to ${r.monitoring.slow_ms} ms`);
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r.monitoring);
+    info(`query insights and logs ${r.monitoring.enabled ? green('on') : dim('off')}  (slow threshold ${r.monitoring.slow_ms} ms)`);
+    return;
+  }
+
+  if (sub === 'insights') {
+    const label = args._[1] ?? 'primary';
+    const path = `${base}/databases/${encodeURIComponent(label)}/insights`;
+    if (args.reset === true) {
+      requireYes(args, 'This clears the collected query statistics for this database.');
+      await apiJSON(creds, 'POST', `${path}/reset`);
+      if (JSON_MODE) return emitJSON({ ok: true });
+      info(`${green('reset')} query statistics for ${bold(label)}`);
+      return;
+    }
+    const sort = typeof args.sort === 'string' ? args.sort : 'total';
+    const r = await apiJSON(creds, 'GET', `${path}?sort=${encodeURIComponent(sort)}&limit=${Number(args.limit ?? 10)}`);
+    if (JSON_MODE) return emitJSON(r.statements);
+    if (r.statements.length === 0) { muted('no statements yet.'); return; }
+    for (const st of r.statements) {
+      info(`${dim(`${st.calls.toLocaleString()}x  avg ${st.mean_ms} ms  total ${Math.round(st.total_ms).toLocaleString()} ms  max ${st.max_ms} ms`)}`);
+      info(`  ${st.query.replace(/\s+/g, ' ').slice(0, 200)}`);
+    }
+    return;
+  }
+
+  if (sub === 'logs') {
+    const label = args._[1] ?? 'primary';
+    const q = new URLSearchParams();
+    if (typeof args.level === 'string') q.set('level', args.level);
+    if (args['min-ms'] !== undefined) q.set('min_ms', String(args['min-ms']));
+    if (typeof args.search === 'string') q.set('q', args.search);
+    q.set('limit', String(Number(args.limit ?? 50)));
+    const r = await apiJSON(creds, 'GET', `${base}/databases/${encodeURIComponent(label)}/logs?${q.toString()}`);
+    if (JSON_MODE) return emitJSON(r.entries);
+    if (r.entries.length === 0) { muted('no matching log lines.'); return; }
+    for (const e of r.entries) {
+      const lvl = e.level === 'ERROR' || e.level === 'FATAL' || e.level === 'PANIC' ? red(e.level) : e.level === 'WARNING' ? yellow(e.level) : dim(e.level);
+      info(`${dim(e.ts)} ${lvl} ${e.message.replace(/\s+/g, ' ')}`);
+      if (e.detail) info(`  ${dim(e.detail.replace(/\s+/g, ' '))}`);
+    }
+    return;
+  }
+
+  if (sub === 'roles') {
+    const label = args._[1] ?? 'primary';
+    const action = args._[2];
+    const path = `${base}/databases/${encodeURIComponent(label)}/roles`;
+    if (action === 'create') {
+      const name = args._[3];
+      if (!name) die('usage: canner db roles <db> create <name> --read-only | --read-write | --replication', 2);
+      const picked = ['read-only', 'read-write', 'replication'].filter((k) => args[k] === true);
+      if (picked.length !== 1) die('choose exactly one of --read-only, --read-write or --replication.', 2);
+      const r = await apiJSON(creds, 'POST', path, { label: name, kind: picked[0].replace('-', '_') });
+      if (JSON_MODE) return emitJSON({ ...r.role, write_exclusion_suggestions: r.write_exclusion_suggestions });
+      info(`${green('created')} ${r.role.kind === 'read_write' ? 'read-write' : r.role.kind === 'replication' ? 'replication' : 'read-only'} role ${bold(r.role.label)}`);
+      info(`  ${cyan(r.role.connection_string)}`);
+      if (r.role.write_excluded_tables?.length) {
+        info(`  ${dim('kept SELECT-only:')} ${r.role.write_excluded_tables.join(', ')}`);
+      }
+      // A recommendation, not applied — surfaced once, here, right when it's actionable. The exact
+      // command is printed so acting on it is a copy-paste, not a lookup.
+      if (r.write_exclusion_suggestions?.length) {
+        info('');
+        info(`${yellow('recommendation:')} these table${r.write_exclusion_suggestions.length === 1 ? '' : 's'} look like a migration or audit ledger by name — if so, keep ${r.write_exclusion_suggestions.length === 1 ? 'it' : 'them'} read-only too:`);
+        for (const t of r.write_exclusion_suggestions) {
+          info(`  ${dim('canner db roles')} ${label} ${dim('write-exclusions')} ${bold(name)} ${dim(t)}`);
+        }
+      }
+      return;
+    }
+    if (action === 'rotate' || action === 'rm') {
+      const name = args._[3];
+      if (!name) die(`usage: canner db roles <db> ${action} <name> --yes`, 2);
+      requireYes(args, action === 'rm' ? `This drops the role "${name}"; anything using its connection string stops working.` : `This gives "${name}" a new password; anything using the old one stops working.`);
+      if (action === 'rm') {
+        await apiJSON(creds, 'DELETE', `${path}/${encodeURIComponent(name)}`);
+        if (JSON_MODE) return emitJSON({ ok: true, deleted: name });
+        info(`${green('deleted')} role ${bold(name)}`);
+      } else {
+        const r = await apiJSON(creds, 'POST', `${path}/${encodeURIComponent(name)}/rotate`);
+        if (JSON_MODE) return emitJSON(r.role);
+        info(`${green('rotated')} ${bold(name)}: ${cyan(r.role.connection_string)}`);
+      }
+      return;
+    }
+    if (action === 'write-exclusions') {
+      const name = args._[3];
+      const table = args._[4];
+      if (!name || !table) die('usage: canner db roles <db> write-exclusions <role> <table>', 2);
+      const r = await apiJSON(creds, 'POST', `${path}/${encodeURIComponent(name)}/write-exclusions`, { table });
+      if (JSON_MODE) return emitJSON(r.role);
+      info(`${green('kept SELECT-only')} on ${bold(name)}: ${r.role.write_excluded_tables.join(', ')}`);
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r.roles);
+    if (r.roles.length === 0) { muted(`no roles on ${label}. Create one with \`canner db roles ${label} create <name> --read-only\`.`); return; }
+    for (const x of r.roles) {
+      info(`${pad(bold(x.label), 22)}${x.kind === 'read_write' ? yellow('read-write') : x.kind === 'replication' ? cyan('replication') : green('read-only')}  ${dim(relTime(x.created_at))}`);
+      info(`  ${cyan(x.connection_string)}`);
+      if (x.external_connection_string) info(`  ${cyan(x.external_connection_string)}`);
+      if (x.write_excluded_tables?.length) info(`  ${dim('kept SELECT-only:')} ${x.write_excluded_tables.join(', ')}`);
+    }
+    return;
+  }
+
+  if (sub === 'offsite') {
+    const action = args._[1];
+    const path = `${base}/backup-destinations`;
+    const listAll = async () => (await apiJSON(creds, 'GET', path)).destinations;
+    const find = async (ref) => {
+      const all = await listAll();
+      const hit = all.find((d) => d.id === ref || d.name.toLowerCase() === String(ref).toLowerCase());
+      if (!hit) die(`no destination "${ref}". List them with: canner db offsite`, 1);
+      return hit;
+    };
+    const fields = (body) => {
+      if (typeof args.endpoint === 'string') body.endpoint = args.endpoint;
+      if (typeof args.bucket === 'string') body.bucket = args.bucket;
+      if (typeof args.region === 'string') body.region = args.region;
+      if (typeof args.folder === 'string') body.prefix = args.folder;
+      if (typeof args['access-key'] === 'string') body.access_key = args['access-key'];
+      if (typeof args['secret-key'] === 'string') body.secret_key = args['secret-key'];
+      return body;
+    };
+    if (action === 'add') {
+      const name = args._[2];
+      const body = fields({ name });
+      if (!name || !body.endpoint || !body.bucket || !body.access_key || !body.secret_key) {
+        die('usage: canner db offsite add <name> --endpoint HOST --bucket NAME --access-key KEY --secret-key SECRET [--region R] [--folder F]', 2);
+      }
+      const r = await apiJSON(creds, 'POST', path, body);
+      if (JSON_MODE) return emitJSON(r.destination);
+      info(`${green('added')} off-site destination ${bold(r.destination.name)} (${r.destination.bucket} at ${r.destination.endpoint}). Test it: canner db offsite test ${r.destination.name}`);
+      return;
+    }
+    if (action === 'edit') {
+      if (!args._[2]) die('usage: canner db offsite edit <name> [--new-name N] [--endpoint HOST] [--bucket NAME] [--access-key KEY] [--secret-key SECRET] [--region R] [--folder F]', 2);
+      const cur = await find(args._[2]);
+      const body = fields({ name: typeof args['new-name'] === 'string' ? args['new-name'] : cur.name });
+      body.endpoint ??= cur.endpoint; body.bucket ??= cur.bucket; body.access_key ??= cur.access_key; body.region ??= cur.region; body.prefix ??= cur.prefix;
+      const r = await apiJSON(creds, 'PUT', `${path}/${cur.id}`, body);
+      if (JSON_MODE) return emitJSON(r.destination);
+      info(`${green('saved')} ${bold(r.destination.name)}. Test it: canner db offsite test ${r.destination.name}`);
+      return;
+    }
+    if (action === 'test') {
+      if (!args._[2]) die('usage: canner db offsite test <name>', 2);
+      const cur = await find(args._[2]);
+      const r = await apiJSON(creds, 'POST', `${path}/${cur.id}/test`);
+      if (JSON_MODE) return emitJSON(r);
+      if (r.ok) info(green(`${cur.name}: the bucket accepted a test file.`));
+      else die(`${cur.name}: the test failed: ${r.error}`);
+      return;
+    }
+    if (action === 'rm') {
+      if (!args._[2]) die('usage: canner db offsite rm <name> --yes', 2);
+      const cur = await find(args._[2]);
+      requireYes(args, `This removes "${cur.name}"${cur.databases ? `; ${cur.databases} database(s) stop copying backups off-site` : ''}. Files already in your bucket stay there but can no longer be used to restore.`);
+      await apiJSON(creds, 'DELETE', `${path}/${cur.id}`);
+      if (JSON_MODE) return emitJSON({ ok: true });
+      info(`${green('removed')} ${bold(cur.name)}`);
+      return;
+    }
+    const all = await listAll();
+    if (JSON_MODE) return emitJSON(all);
+    if (all.length === 0) { muted('no off-site destinations. Add one with `canner db offsite add <name> --endpoint HOST --bucket NAME --access-key KEY --secret-key SECRET`.'); return; }
+    for (const d of all) {
+      info(`${bold(d.name)}  ${d.bucket} at ${cyan(d.endpoint)}  region ${d.region}  folder ${d.prefix || dim('(root)')}`);
+      info(`  access key ${d.access_key}  ${d.last_test_at ? (d.last_test_ok ? green('test ok') : red('test failed')) + ' ' + dim(relTime(d.last_test_at)) : dim('not tested')}  ${d.databases ? dim(`${d.databases} database(s)`) : ''}`);
+    }
+    return;
+  }
+
+  if (sub === 'alerts') {
+    const action = args._[1];
+    const path = `${base}/database-alerts`;
+    if (action === 'test') {
+      const r = await apiJSON(creds, 'POST', `${path}/test`);
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('sent')} ${r.emails} email${r.emails === 1 ? '' : 's'}${r.webhook === 'sent' ? ' and the webhook' : r.webhook === 'failed' ? `; the webhook ${red('failed')}: ${r.error}` : ''}`);
+      return;
+    }
+    if (action === 'set') {
+      const patch = {};
+      const onOff = (v, name) => { if (v !== 'on' && v !== 'off') die(`--${name} takes on or off.`, 2); return v === 'on'; };
+      if (args.email !== undefined) patch.email_enabled = onOff(args.email, 'email');
+      if (args.verify !== undefined) patch.verify_backups = onOff(args.verify, 'verify');
+      if (args.recipients !== undefined) patch.recipients = args.recipients === 'all' ? [] : String(args.recipients).split(',').map((x) => x.trim()).filter(Boolean);
+      if (args.webhook !== undefined) patch.webhook_url = args.webhook === 'none' ? null : String(args.webhook);
+      if (args['rotate-secret'] === true) patch.rotate_webhook_secret = true;
+      if (Object.keys(patch).length === 0) die('nothing to change. Use --email, --recipients, --webhook, --rotate-secret or --verify.', 2);
+      const r = await apiJSON(creds, 'PATCH', path, patch);
+      if (JSON_MODE) return emitJSON(r);
+      info(`${green('saved')} alert settings`);
+      if (r.webhook_secret) info(`  webhook signing secret (shown once): ${cyan(r.webhook_secret)}`);
+      return;
+    }
+    const r = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(r);
+    const c = r.settings;
+    info(`${bold('email')}      ${c.email_enabled ? green('on') : dim('off')} → ${r.effective_recipients.join(', ') || dim('(nobody)')}${c.recipients.length ? '' : dim('  (all org admins)')}`);
+    info(`${bold('webhook')}    ${c.webhook_url ? cyan(c.webhook_url) : dim('none')}`);
+    info(`${bold('verify')}     ${c.verify_backups ? green('on') : dim('off')}  ${dim('(test-restore backups overnight)')}`);
+    const open = r.incidents.filter((i) => i.state === 'open');
+    if (open.length === 0) muted('no open problems.');
+    for (const i of open) info(`  ${i.severity === 'critical' ? red(i.kind) : yellow(i.kind)} ${i.database ?? ''} ${dim(relTime(i.first_seen_at))}${i.detail?.error ? ' ' + dim(i.detail.error) : ''}`);
+    return;
+  }
+
+  if (sub === 'instance') {
+    const action = args._[1];
+    const path = `${base}/instance`;
+
+    if (!action || action === 'show') {
+      const body = await apiJSON(creds, 'GET', path);
+      if (JSON_MODE) return emitJSON(body);
+      const i = body?.instance;
+      if (!i) {
+        muted(body?.allowed ? 'no dedicated instance yet. Create one with `canner db instance create`.' : 'A dedicated Postgres instance is a paid add-on for this project.');
+        return;
+      }
+      info(`${bold('dedicated instance')}  ${i.state === 'running' ? green(i.state) : yellow(i.state)}  ${dim(`Postgres ${i.pg_version} · ${i.databases} database${i.databases === 1 ? '' : 's'}`)}`);
+      info(`  point-in-time recovery  ${i.pitr_enabled ? green(`on (${i.pitr_window_days}-day window)`) : dim('off')}${i.pitr_enabled ? dim(`  archive ${i.archive_mb} MB`) : ''}`);
+      if (i.error) info(`  ${red(i.error)}`);
+      return;
+    }
+
+    if (action === 'create') {
+      const body = await apiJSON(creds, 'POST', path, {
+        ...(args.pg ? { pg_version: String(args.pg) } : {}),
+        ...(args.pitr === true ? { pitr: true } : {}),
+        ...(args.window ? { window_days: Number(args.window) } : {}),
+      });
+      if (JSON_MODE) return emitJSON(body);
+      const i = body?.instance;
+      info(`${green('created')} a dedicated Postgres ${i.pg_version} instance${i.pitr_enabled ? ` with point-in-time recovery (${i.pitr_window_days}-day window)` : ''}`);
+      muted('Add databases to it with `canner db create <name> --instance`, or move one with `canner db move <name> --to instance --yes`.');
+      return;
+    }
+
+    if (action === 'stop' || action === 'start') {
+      if (action === 'stop') requireYes(args, 'Stopping takes every database on the instance offline (data is kept).');
+      const body = await apiJSON(creds, 'POST', `${path}/power`, { action, ...(action === 'stop' ? { confirm: true } : {}) });
+      if (JSON_MODE) return emitJSON(body);
+      info(`${green(action === 'stop' ? 'stopped' : 'started')} the dedicated instance`);
+      return;
+    }
+
+    if (action === 'destroy') {
+      requireYes(args, 'This permanently destroys the instance and its point-in-time-recovery archive. Every database on it must be moved or deleted first.');
+      await apiJSON(creds, 'DELETE', `${path}?confirm=true`);
+      if (JSON_MODE) return emitJSON({ ok: true });
+      info(`${green('destroyed')} the dedicated instance`);
+      return;
+    }
+
+    die('usage: canner db instance [show] | create [--pg 17|18] [--pitr] [--window DAYS] | start | stop --yes | destroy --yes', 2);
+  }
+
+  if (sub === 'pitr') {
+    const path = `${base}/instance/pitr`;
+    if (args.now === true) {
+      const started = await apiJSON(creds, 'POST', `${base}/instance/base-backups`);
+      const op = started?.operation;
+      if (!op) die('the platform did not return an operation.');
+      if (args['no-wait'] === true) { if (JSON_MODE) return emitJSON(op); info(`${green('started')} base backup ${dim(op.id)}`); return; }
+      if (!JSON_MODE) info('taking a base backup…');
+      const done = await waitForOperation(creds, base, op.id, args);
+      if (JSON_MODE) return emitJSON(done);
+      info(`${green('done')} ${done.result?.bytes != null ? dim(`(${fmtBytes(done.result.bytes)})`) : ''}`);
+      return;
+    }
+    if (args.offsite !== undefined) {
+      // --offsite <destination name|id>  |  --offsite none
+      let destination_id = null;
+      if (args.offsite !== 'none') {
+        const dl = await apiJSON(creds, 'GET', `${base}/backup-destinations`);
+        const want = String(args.offsite);
+        const hit = dl.destinations.find((d) => d.id === want || d.name.toLowerCase() === want.toLowerCase());
+        if (!hit) die(`no off-site destination named "${want}". Add one first: canner db offsite add ...`, 2);
+        destination_id = hit.id;
+      }
+      const body = await apiJSON(creds, 'PATCH', `${base}/instance/archive-offsite`, { destination_id });
+      if (JSON_MODE) return emitJSON(body);
+      const o = body.archive_offsite;
+      info(o.destination_id ? `${green('set')} the recovery archive is copied off-site to ${bold(o.destination_name)}` : `${green('set')} the recovery archive is no longer copied off-site`);
+      return;
+    }
+    const setting = args.enable === true || args.disable === true || args.window !== undefined || args.every !== undefined;
+    if (setting) {
+      if (args.disable === true) requireYes(args, 'Turning off point-in-time recovery permanently deletes the recovery archive.');
+      const patch = {};
+      if (args.enable === true) patch.enabled = true;
+      if (args.disable === true) { patch.enabled = false; patch.confirm = true; }
+      if (args.window !== undefined) patch.window_days = Number(args.window);
+      if (args.every !== undefined) patch.base_backup_interval_hours = Number(args.every);
+      const body = await apiJSON(creds, 'PATCH', path, patch);
+      if (JSON_MODE) return emitJSON(body);
+      const i = body.instance;
+      info(`${green('set')} point-in-time recovery: ${i.pitr_enabled ? `on, ${i.pitr_window_days}-day window, base backup every ${i.base_backup_interval_hours}h` : 'off'}`);
+      return;
+    }
+    const body = await apiJSON(creds, 'GET', path);
+    if (JSON_MODE) return emitJSON(body);
+    const p = body.pitr;
+    info(`${bold('point-in-time recovery')}  ${p.enabled ? green('on') : dim('off')}`);
+    if (p.enabled) {
+      info(`  restorable from ${p.earliest ? cyan(p.earliest) : dim('(first base backup pending)')} to ${p.latest_archived ? cyan(p.latest_archived) : dim('now')}`);
+      info(`  ${p.window_days}-day window · base backup every ${p.base_backup_interval_hours}h · ${p.base_backups} base backup${p.base_backups === 1 ? '' : 's'} · archive ${p.archive_mb} MB`);
+      if (p.archive_failures > 0) info(`  ${red(`${p.archive_failures} WAL archive failure(s) — contact support`)}`);
+      const o = body.archive_offsite;
+      if (o?.destination_id) {
+        info(`  off-site copy: ${bold(o.destination_name)} · ${o.files} file${o.files === 1 ? '' : 's'} (${fmtBytes(o.bytes)})${o.pending ? ` · ${o.pending} waiting` : ''}${o.last_at ? ` · last ${relTime(o.last_at)}` : ''}`);
+        if (o.error) info(`  ${red(`last copy failed: ${o.error}`)}`);
+      } else if (p.archive_encrypted) {
+        info(`  off-site copy: ${dim('off (canner db pitr --offsite <destination>)')}`);
+      }
+    }
+    return;
+  }
+
+  if (sub === 'pitr-restore') {
+    const label = args._[1];
+    const to = typeof args.to === 'string' ? args.to : null;
+    if (!label || !to) die('usage: canner db pitr-restore <name> --to <ISO-8601 time | latest>', 2);
+    const started = await apiJSON(creds, 'POST', `${base}/databases/${encodeURIComponent(label)}/pitr-restore`, { target: to });
+    const op = started?.operation;
+    const into = started?.database?.name;
+    if (!op) die('the platform did not return an operation.');
+    if (args['no-wait'] === true) {
+      if (JSON_MODE) return emitJSON(started);
+      info(`${green('started')} recovery ${dim(op.id)} → ${bold(into)}`);
+      return;
+    }
+    if (!JSON_MODE) info(`recovering ${label} as of ${to} into ${into}…`);
+    const done = await waitForOperation(creds, base, op.id, args);
+    if (JSON_MODE) return emitJSON({ ...done, database: started.database });
+    info(`${green('recovered')} ${bold(label)} as of ${to} → new database ${bold(into)}`);
+    muted(`Nothing existing was touched. To swap it in: canner db copy ${into} ${label} --replace`);
+    return;
+  }
+
+  if (sub === 'move') {
+    const label = args._[1];
+    const to = typeof args.to === 'string' ? args.to : null;
+    if (!label || (to !== 'instance' && to !== 'shared')) die('usage: canner db move <name> --to instance|shared --yes', 2);
+    requireYes(args, 'Moving a database has real downtime while it runs (the connection string does not change; a failed move leaves it untouched).');
+    const done = await startAndWait(creds, base, args, 'POST', `${base}/databases/${encodeURIComponent(label)}/move`, { to, confirm: true }, 'moving');
+    if (!done) return;
+    if (JSON_MODE) return emitJSON(done);
+    info(`${green('moved')} ${bold(label)} to ${to === 'instance' ? 'the dedicated instance' : 'shared hosting'}`);
+    return;
+  }
+
+  die(`unknown db subcommand "${sub}". Use: list | init | create | info | url | rm | pg-version | export | import | migrate-in | migrate-out | copy | ops | external | rotate | backup-policy | backup | backups | diff | inspect | alerts | roles | offsite | metrics | monitoring | insights | logs | resources | extensions | tuning | restart | replication | subscriptions | instance | pitr | pitr-restore | move.`, 2);
+}
+
 function printHelp() {
   process.stdout.write(`${bold('canner')} ${dim('— deploy to Canner from any terminal')}
 
@@ -1180,6 +2381,98 @@ ${bold('Resources:')}
   ${bold('domains')} rm <hostname|id> [--slug X]
                        Manage a project's custom domains.
 
+${bold('Databases:')}
+  ${bold('db')} [list] [--slug X]           List the project's databases.
+  ${bold('db')} init | create <name> [--pg 17|18]
+                       Provision the primary database, or add another (paid).
+  ${bold('db')} info [<name>] [--reveal] | url [<name>]
+                       Connection details (password hidden unless --reveal).
+  ${bold('db')} export [<name>] [--format custom|plain] [--out FILE]
+  ${bold('db')} import <file> [--to <name>] [--replace]
+  ${bold('db')} migrate-in --from <url>|--from-env VAR [--to <name>] [--replace]
+  ${bold('db')} migrate-out --to-url <url>|--to-env VAR [--from <name>] --yes
+  ${bold('db')} copy <from> <to> [--to-project SLUG] [--replace]
+  ${bold('db')} rm <name> --yes | pg-version <name> <17|18> --yes | ops [<id>]
+                       Move data in and out, copy between databases, and
+                       manage them. Long operations run on Canner; the CLI
+                       waits (or use --no-wait).
+  ${bold('db')} external [<name>]           Show external-access status.
+  ${bold('db')} external <name> --enable --allow CIDR [--allow CIDR ...]
+                       Turn on public access, allowed from only these
+                       addresses (repeat --allow; or --allow-all --yes for
+                       0.0.0.0/0 — not recommended).
+  ${bold('db')} external <name> --disable   Turn public access off.
+  ${bold('db')} rotate <name> --yes         Rotate the database password.
+  ${bold('db')} backup-policy [<name>]      Show a database's backup schedule.
+  ${bold('db')} backup-policy <name> --enable --every HOURS --keep DAYS [--keep-count N|none]
+  ${bold('db')} backup-policy <name> --disable
+                       Turn scheduled backups on/off and set how often and how
+                       long they're kept (paid plans).
+  ${bold('db')} backup [<name>]             Take a manual backup now (waits by
+                       default, or use --no-wait).
+  ${bold('db')} backups [<name>]            List backups for a database.
+  ${bold('db')} backups <name> <id>         Show one backup.
+  ${bold('db')} backups <name> <id> --download [--out FILE]
+                       Download the decrypted dump.
+  ${bold('db')} backups <name> <id> --restore --inspect
+                       Restore into a temporary inspect database (own
+                       connection string, never injected, expires).
+  ${bold('db')} backups <name> <id> --verify
+                       Test-restore the backup into a scratch database.
+  ${bold('db')} diff <name> [--against <name>]
+                       Compare tables, columns and row counts (default: the
+                       database an inspect database was restored from).
+  ${bold('db')} inspect <name> --keep | --extend HOURS
+  ${bold('db')} resources                   Show the memory budget shared by the app and the dedicated instance.
+  ${bold('db')} resources set [--share PCT] [--app-reserved GB]   Postgres's share of the shared memory (10-90); reserved RAM kept for the app.
+  ${bold('db')} resources apply --yes       Size Postgres for it and set its memory limit (restarts the instance).
+  ${bold('db')} extensions [<name>] [install|update|rm <ext>] [--window] [--yes]   Extensions on the dedicated instance (pgvector, PostGIS, pg_trgm, pg_cron, ...).
+  ${bold('db')} tuning [--preset balanced|read-heavy|write-heavy|analytics] [--statement-timeout S] [--idle-timeout S] [--lock-timeout S]
+                       [--window-day 0-6|all] [--window-hour 0-23] [--window-tz ZONE]   Workload preset, timeouts and the maintenance window.
+  ${bold('db')} restart --yes               Restart the dedicated instance now (also applies settings waiting for the window).
+  ${bold('db')} replication [<name>] [on [--cap MB] [--window] --yes | off --yes | cap MB | pub <n> --all|--tables a.b,c.d | unpub <n> --yes | drop-slot <n> --yes]
+                       Logical replication: turn on (restarts), the WAL cap per slot, publications, slots. Subscribers sign in with \`db roles <name> create <n> --replication\`.
+  ${bold('db')} subscriptions [<name>] [add <n> --from <url>|--from-env VAR --publication p1,p2 [--no-copy] | refresh|pause|resume <n> | rm <n> [--force] --yes]
+                       Follow publications on an external server (live copy / no-downtime migration).
+  ${bold('db')} metrics [<name>] [--range 1h|24h|7d|30d]   Transactions, connections, cache hit, size (and instance memory/CPU).
+  ${bold('db')} monitoring [on|off --yes] [--slow-ms N]     Query insights + logs on the dedicated instance (restarts it).
+  ${bold('db')} insights [<name>] [--sort total|mean|calls|max] [--limit N] | --reset --yes
+  ${bold('db')} logs [<name>] [--level ERROR,WARNING] [--min-ms N] [--search TEXT] [--limit N]
+  ${bold('db')} roles [<name>]              List a database's roles (read-only / read-write logins).
+  ${bold('db')} roles <name> create <role> --read-only | --read-write
+                       A read-write role keeps a migration ledger (schema_migrations and similar)
+                       SELECT-only automatically; the response may suggest other candidates by name.
+  ${bold('db')} roles <name> rotate <role> --yes
+  ${bold('db')} roles <name> rm <role> --yes
+  ${bold('db')} roles <name> write-exclusions <role> <table>
+                       Keep one more table SELECT-only for a read-write role, live — no recreation.
+  ${bold('db')} offsite                     List the off-site backup destinations (S3-compatible buckets).
+  ${bold('db')} offsite add <name> --endpoint HOST --bucket NAME --access-key KEY --secret-key SECRET [--region R] [--folder F]
+  ${bold('db')} offsite edit <name> [--new-name N] [--endpoint HOST] [--bucket NAME] [--access-key KEY] [--secret-key SECRET] [--region R] [--folder F]
+  ${bold('db')} offsite test <name> | rm <name> --yes
+  ${bold('db')} backup-policy <name> --offsite <destination>|off   Copy this database's backups off-site to that destination.
+  ${bold('db')} backups <name> <id> --offsite [destination]        Copy one backup off-site now (default: the policy's destination).
+  ${bold('db')} alerts                      Show alert settings and open problems.
+  ${bold('db')} alerts set [--email on|off] [--recipients a@x.com,b@y.com|all]
+                       [--webhook URL|none] [--rotate-secret] [--verify on|off]
+  ${bold('db')} alerts test                 Send a test alert.
+  ${bold('db')} backups <name> <id> --restore [--no-wait]
+                       Restore into a brand-new database (safe default).
+  ${bold('db')} backups <name> <id> --restore --to <name> --yes
+                       Restore IN PLACE into an existing database, replacing
+                       its contents (Canner snapshots it first).
+  ${bold('db')} backups <name> <id> --rm --yes
+                       Delete a backup (destroys its key immediately).
+  ${bold('db')} instance [create [--pg 17|18] [--pitr] [--window DAYS] | start | stop --yes | destroy --yes]
+                       A dedicated Postgres server for this project (paid add-on).
+  ${bold('db')} create <name> --instance      Create a database on the dedicated instance.
+  ${bold('db')} move <name> --to instance|shared --yes
+                       Move a database onto/off the instance (same connection string).
+  ${bold('db')} pitr [--enable | --disable --yes] [--window DAYS] [--every HOURS] [--now] [--offsite <destination>|none]
+                       Point-in-time recovery: status, settings, or a base backup now.
+  ${bold('db')} pitr-restore <name> --to <ISO time | latest>
+                       Recover a database as of a moment into a NEW database.
+
 ${bold('Global:')}
   ${bold('--json')}               Emit machine-readable JSON (for scripts, CI, agents).
                        Suppresses tables + progress; --follow log streaming is
@@ -1199,6 +2492,8 @@ ${bold('Examples:')}
   canner env set API_KEY=secret --sensitive  ${dim('# add a hidden env var')}
   canner env list --reveal                ${dim('# show sensitive values in cleartext')}
   canner domains add www.example.com      ${dim('# attach a custom domain')}
+  canner db export --out backup.dump      ${dim('# download a pg_dump of the primary database')}
+  canner db import backup.dump --to analytics  ${dim('# restore a dump into another database')}
   canner projects --json | jq '.[].slug'  ${dim('# machine-readable output')}
 
 ${bold('Environment:')}
@@ -1253,6 +2548,9 @@ const dispatch = {
   tokens: cmdToken,
   env: cmdEnv,
   domains: cmdDomains,
+  db: cmdDb,
+  database: cmdDb,
+  databases: cmdDb,
 };
 const handler = dispatch[command];
 if (!handler) {