@everystack/cli 0.4.32 → 0.4.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.32",
+  "version": "0.4.33",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -100,6 +100,7 @@
     "@aws-sdk/client-lambda": "3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",
     "@aws-sdk/client-ssm": "3.1053.0",
+    "@aws-sdk/lib-storage": "3.1053.0",
     "@aws-sdk/client-sts": "3.1053.0",
     "@aws-sdk/signature-v4a": "3.1048.0",
     "glob": "13.0.6",

package/src/cli/aws.ts

@@ -13,7 +13,7 @@ let lambdaClient: InstanceType<typeof import('@aws-sdk/client-lambda').LambdaCli
 let kvsClient: InstanceType<typeof import('@aws-sdk/client-cloudfront-keyvaluestore').CloudFrontKeyValueStoreClient> | null = null;
 let rdsClient: InstanceType<typeof import('@aws-sdk/client-rds').RDSClient> | null = null;
 
-async function getS3(region: string) {
+export async function getS3(region: string) {
   if (!s3Client) {
     const { S3Client } = await importOptionalAws(
       () => import('@aws-sdk/client-s3'), '@aws-sdk/client-s3', 'this command',

package/src/cli/commands/db-backup.ts

@@ -4,14 +4,152 @@
  * db:backup/db:export run in the ephemeral Task lane (the ops Lambda holds no pg binaries); the CLI
  * dispatches and polls. db:backups/db:restore/download are thin invokeAction wrappers. The image's
  * version handshake is the compatibility gate — verify a deploy with `everystack task:probe`.
+ *
+ * db:backup has a SECOND venue for break-glass: `--database-url <local> --stage <target>` dumps a
+ * LOCAL database and uploads it into the target stage's backups bucket as a db:backup-shaped object
+ * (same key scheme + .meta.json + dump flags as a server backup). The standard credential-free
+ * `db:restore --from <id> --stage <target>` then lands it via the Task lane (pg_restore runs as the
+ * privileged `migrator` role, which can CREATE SCHEMA + own objects). The local dump is the only
+ * held connection; the upload rides the operator's AWS credentials — the same trust boundary as
+ * db:fork's cross-stage presign. This is the sanctioned local→stage full replace on a role-managed
+ * stage (raw pg_restore can't: the operator/api role can't CREATE SCHEMA, and only the master could).
  */
 
+import { spawn } from 'node:child_process';
+import { createGzip } from 'node:zlib';
+import { pipeline } from 'node:stream/promises';
+import { randomBytes } from 'node:crypto';
 import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
-import { invokeAction, presignGet } from '../aws.js';
-import { parseBackupRef, keyForId, crossStageGuard, restoreTargetGuard } from '../backup.js';
+import { invokeAction, presignGet, getS3 } from '../aws.js';
+import {
+  parseBackupRef, keyForId, crossStageGuard, restoreTargetGuard,
+  backupKey, backupId, metaKey, utcStamp,
+} from '../backup.js';
+import { pgEnvFromUrl } from './db.js';
 import { pollTaskUntilStopped } from '../task-poll.js';
 import { step, success, fail, info, warn } from '../output.js';
 
+/** Which database db:backup dumps. LOCAL requires a target --stage (its bucket receives the upload
+ *  AND names the backup id). Note this DIVERGES from db:export, where --database-url and --stage are
+ *  mutually-exclusive venues: here the local venue COMBINES them (dump local → upload to the stage). */
+export type BackupVenue =
+  | { kind: 'local'; url: string; stage: string }
+  | { kind: 'stage'; stage: string | undefined };
+
+export function resolveBackupVenue(flags: Record<string, string>): BackupVenue {
+  const url = flags['database-url'];
+  if (url) {
+    if (!flags.stage) {
+      throw new Error(
+        'db:backup --database-url <local> also needs --stage <target> — the local dump uploads into '
+        + "that stage's backups bucket, and the stage names the backup id `db:restore --from` consumes.",
+      );
+    }
+    return { kind: 'local', url, stage: flags.stage };
+  }
+  return { kind: 'stage', stage: flags.stage };
+}
+
+/**
+ * Full-DB streaming pg_dump args — IDENTICAL to the server's db:backup dump (packages/server
+ * backup.ts pgDumpArgs()), minus `-f`: streamed to stdout so it pipes into gzip → S3. Excludes the
+ * everystack ops schema (task_log/schema_log/etc — the TARGET's own audit history, not app data;
+ * restoring it would rewind that history AND makes pg_restore --clean fail on DROP SCHEMA everystack).
+ */
+export function pgDumpFullArgs(): string[] {
+  return ['-Fc', '--no-owner', '--no-privileges', '--no-comments', '--exclude-schema=everystack'];
+}
+
+/** The .meta.json sidecar — byte-shape identical to the server's runBackup meta (backup-run.ts:156),
+ *  so db:backups list and the destructive-apply gate read a local upload exactly like a stage backup.
+ *  `bytes` is undefined-safe (JSON.stringify drops it) exactly as the server leaves it on a failed
+ *  HeadObject — never coerced to 0. */
+export function localBackupMeta(opts: {
+  id: string;
+  stage: string;
+  createdAt: Date;
+  bytes?: number;
+  key: string;
+}): Record<string, unknown> {
+  return {
+    id: opts.id,
+    stage: opts.stage,
+    createdAt: opts.createdAt.toISOString(),
+    bytes: opts.bytes,
+    key: opts.key,
+  };
+}
+
+/**
+ * Stream a local database into a stage's backups bucket as a db:backup-shaped object. Mirrors the
+ * server's runBackup streaming AND its load-bearing correctness rule: a completed S3 multipart upload
+ * does NOT mean pg_dump succeeded (pg_dump can exit non-zero mid-stream while the upload "completes"),
+ * so we await the child exit code SEPARATELY and, on any failure, abort the upload and delete the
+ * partial object. A backup tool that ships a truncated dump is worse than none.
+ */
+export async function runLocalBackupUpload(deps: {
+  region: string;
+  bucket: string;
+  url: string;
+  stage: string;
+}): Promise<{ id: string; key: string; bytes?: number }> {
+  const now = new Date();
+  const stamp = utcStamp(now);
+  const shortId = randomBytes(3).toString('hex');
+  const key = backupKey(deps.stage, stamp, shortId);
+  const id = backupId(deps.stage, stamp, shortId);
+  const mkey = metaKey(key);
+
+  const env = { ...process.env, ...pgEnvFromUrl(deps.url) };
+  const s3 = await getS3(deps.region);
+  const { Upload } = await import('@aws-sdk/lib-storage');
+  const { DeleteObjectCommand, PutObjectCommand, HeadObjectCommand } = await import('@aws-sdk/client-s3');
+
+  const child = spawn('pg_dump', pgDumpFullArgs(), { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  const childExit = new Promise<void>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', (code) =>
+      code === 0 ? resolve() : reject(new Error(`pg_dump exited ${code}: ${stderr.trim()}`)));
+  });
+
+  const gzip = createGzip();
+  const upload = new Upload({
+    client: s3,
+    params: {
+      Bucket: deps.bucket, Key: key, Body: gzip,
+      ContentType: 'application/gzip', ServerSideEncryption: 'AES256',
+    },
+  });
+
+  try {
+    await Promise.all([
+      pipeline(child.stdout!, gzip), // pg_dump → gzip; errors propagate, streams destroyed
+      upload.done(),                 // gzip → S3 multipart
+      childExit,                     // the guard: non-zero pg_dump rejects the whole thing
+    ]);
+  } catch (err) {
+    try { await upload.abort(); } catch { /* may already have completed */ }
+    await s3.send(new DeleteObjectCommand({ Bucket: deps.bucket, Key: key })).catch(() => {});
+    throw err;
+  }
+
+  let bytes: number | undefined;
+  try {
+    const head = await s3.send(new HeadObjectCommand({ Bucket: deps.bucket, Key: key }));
+    bytes = head.ContentLength;
+  } catch { /* size is best-effort */ }
+
+  await s3.send(new PutObjectCommand({
+    Bucket: deps.bucket, Key: mkey,
+    Body: JSON.stringify(localBackupMeta({ id, stage: deps.stage, createdAt: now, bytes, key })),
+    ContentType: 'application/json', ServerSideEncryption: 'AES256',
+  }));
+
+  return { id, key, bytes };
+}
+
 function fmtBytes(n?: number): string {
   if (n == null) return '-';
   if (n < 1024) return `${n} B`;
@@ -27,6 +165,53 @@ function fmtBytes(n?: number): string {
  * the compatibility gate (a too-old image fails the run loudly — no separate layer pre-flight).
  */
 export async function dbBackupCommand(flags: Record<string, string>): Promise<void> {
+  let venue: BackupVenue;
+  try {
+    venue = resolveBackupVenue(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // Local venue: dump a reachable database here and upload it into the target stage's backups bucket
+  // as a db:backup-shaped object, so `db:restore --from <id> --stage <target>` lands it credential-free.
+  if (venue.kind === 'local') {
+    step('Resolving deployed config...');
+    let config: CliConfig;
+    try {
+      config = await resolveConfig(venue.stage);
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+    if (!config.backupsBucket) {
+      fail('No backupsBucket in the deployed config. Add `backupsBucket: backups.name` to sst.config outputs and redeploy.');
+      process.exit(1);
+    }
+    info(`Region: ${config.region}, Bucket: ${config.backupsBucket}`);
+    // Version gate for the local venue: unlike the stage venue (whose pg binaries are the Task image),
+    // this dumps with the OPERATOR's pg_dump. pg_restore refuses an archive from a NEWER pg_dump major,
+    // so a mismatch surfaces only at restore time ("unsupported version in file header") — loud and
+    // lossless (it fails before --clean drops anything), but discovered exactly when you need the
+    // backup. Surface the local major up front so the operator can match it to the target's PG major.
+    try {
+      const { execFileSync } = await import('node:child_process');
+      const v = execFileSync('pg_dump', ['--version']).toString().trim();
+      info(`Local ${v} — must be ≤ the target stage's PostgreSQL major, or db:restore will reject the dump.`);
+    } catch { /* a missing pg_dump surfaces loudly in the dump step below */ }
+    step(`Running pg_dump (full, --exclude-schema=everystack) against --database-url → S3 (this may take a while for large databases)...`);
+    try {
+      const res = await runLocalBackupUpload({
+        region: config.region, bucket: config.backupsBucket, url: venue.url, stage: venue.stage,
+      });
+      success(`Backup ${res.id} (${fmtBytes(res.bytes)}). Restore with: everystack db:restore --from ${res.id} --stage ${venue.stage} --confirm`);
+    } catch (err: any) {
+      fail(`Backup failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   step('Resolving deployed config...');
   let config: CliConfig;
   try {

package/src/cli/index.ts

@@ -368,7 +368,7 @@ Usage:
   everystack db:provision      --stage <name> [--direct | --database-url <url>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB). No flag = ops-Lambda venue (auto-falls to direct via the ADMIN_DATABASE_URL secret if the handler has no dbPlugin). --direct = direct connection reading that secret (master never on argv); --database-url = explicit URL. Declared schemas are set as the ROLE default (ALTER ROLE … SET search_path) — the secret stays credentials-only, and the URL is libpq-clean
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
   everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
-  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id)
+  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id). Add --database-url <local> --stage <target> to dump a LOCAL database and upload it into the target stage's bucket as a restorable backup — the credential-free break-glass local→stage full replace (then: db:restore --from <id> --stage <target>)
   everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)