@rebasepro/server-postgres 0.0.1-canary.4829d6e

package/src/backup/backup-cli.ts

@@ -0,0 +1,383 @@
+/**
+ * CLI handlers for `rebase db backup`, `rebase db restore`, and
+ * `rebase db backups list`. Kept out of the main `cli.ts` dispatcher so the
+ * backup surface stays self-contained.
+ */
+import arg from "arg";
+import path from "path";
+import fs from "fs";
+import os from "os";
+import readline from "readline";
+import chalk from "chalk";
+import { logger } from "@rebasepro/server";
+import type { StorageController } from "@rebasepro/server";
+import {
+    BackupDestination,
+    parseBackupDestination,
+    parseDbNameFromUrl,
+    resolveConnectionString,
+    withDatabaseName
+} from "./pg-tools";
+import {
+    BackupToolError,
+    createDump,
+    ensureDatabaseExists,
+    listBackups,
+    preflight,
+    restoreDump,
+    uploadBackup
+} from "./backup-service";
+
+function formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+/**
+ * Build a StorageController for an object-storage destination from the same
+ * `S3_*` env vars the backend uses. Returns `null` for local destinations.
+ */
+async function resolveStorageForDestination(
+    dest: BackupDestination,
+    env: Record<string, string | undefined>
+): Promise<StorageController | null> {
+    if (dest.kind === "local") return null;
+    if (dest.kind === "gcs") {
+        const { GCSStorageController } = await import("@rebasepro/server");
+        return new GCSStorageController({ type: "gcs", bucket: dest.bucket });
+    }
+    // s3 (also covers R2/MinIO/Hetzner/GCS-interop via S3_ENDPOINT)
+    if (!env.S3_ACCESS_KEY_ID || !env.S3_SECRET_ACCESS_KEY) {
+        throw new BackupToolError(
+            "S3 destination requires S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY in the environment.",
+            "Set the same S3_* variables your backend uses for storage."
+        );
+    }
+    const { S3StorageController } = await import("@rebasepro/server");
+    return new S3StorageController({
+        type: "s3",
+        bucket: dest.bucket,
+        region: env.S3_REGION || "auto",
+        accessKeyId: env.S3_ACCESS_KEY_ID,
+        secretAccessKey: env.S3_SECRET_ACCESS_KEY,
+        endpoint: env.S3_ENDPOINT,
+        forcePathStyle: env.S3_FORCE_PATH_STYLE === "true"
+    });
+}
+
+function requireConnection(): string {
+    const conn = resolveConnectionString(process.env);
+    if (!conn) {
+        logger.error(chalk.red("✗ DATABASE_URL is not set. Make sure your .env file is configured."));
+        process.exit(1);
+    }
+    return conn;
+}
+
+async function promptConfirm(question: string): Promise<boolean> {
+    // Non-interactive shells (CI, pipes) can't answer — treat as "no".
+    if (!process.stdin.isTTY) return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer: string = await new Promise((resolve) => rl.question(question, resolve));
+        return /^y(es)?$/i.test(answer.trim());
+    } finally {
+        rl.close();
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// rebase db backup
+// ─────────────────────────────────────────────────────────────────────────
+export async function backupCommand(rawArgs: string[]): Promise<void> {
+    const args = arg(
+        {
+            "--out": String,
+            "--exclude-schema": [String],
+            "--no-owner": Boolean,
+            "-o": "--out"
+        },
+        { argv: rawArgs.slice(2), permissive: true }
+    );
+
+    if (args._.includes("--help") || rawArgs.includes("--help")) {
+        printBackupHelp();
+        return;
+    }
+
+    const connectionString = requireConnection();
+    const dbName = parseDbNameFromUrl(connectionString) ?? "database";
+    const out = args["--out"] || process.env.BACKUP_DESTINATION || path.join(process.cwd(), "backups");
+    const dest = parseBackupDestination(out);
+
+    logger.info("");
+    logger.info(chalk.bold("  💾 Rebase DB Backup"));
+    logger.info(chalk.gray(`  Database:    ${dbName}`));
+    logger.info(chalk.gray(`  Destination: ${out}`));
+    logger.info("");
+
+    // Version pre-flight (doctor-style).
+    const pf = await preflight("pg_dump", connectionString);
+    if (!pf.compatible) {
+        logger.error(chalk.red(`  ✗ ${pf.reason}`));
+        process.exit(1);
+    }
+    logger.info(chalk.gray(`  Using pg_dump ${pf.toolMajor} against server ${pf.serverMajor}.`));
+
+    try {
+        if (dest.kind === "local") {
+            // Honour an explicit `…/name.dump` path; otherwise treat it as a
+            // directory and auto-name the file.
+            const explicitFile = dest.path.endsWith(".dump");
+            const dump = await createDump({
+                connectionString,
+                dbName,
+                outDir: explicitFile ? path.dirname(dest.path) : dest.path,
+                fileName: explicitFile ? path.basename(dest.path) : undefined,
+                excludeSchemas: args["--exclude-schema"],
+                noOwner: args["--no-owner"],
+                inheritStdio: true
+            });
+            logger.info("");
+            logger.info(chalk.green(`  ✓ Backup written to ${dump.localFile} (${formatBytes(dump.sizeBytes)})`));
+        } else {
+            const storage = await resolveStorageForDestination(dest, process.env);
+            const dump = await createDump({
+                connectionString,
+                dbName,
+                excludeSchemas: args["--exclude-schema"],
+                noOwner: args["--no-owner"],
+                inheritStdio: true
+            });
+            try {
+                const uploaded = await uploadBackup(storage!, dump.localFile, dest);
+                logger.info("");
+                logger.info(chalk.green(`  ✓ Backup uploaded to ${uploaded.storageUrl} (${formatBytes(dump.sizeBytes)})`));
+                logger.info(chalk.gray("    Ensure this bucket is private — backups may contain secrets and PII."));
+            } finally {
+                if (fs.existsSync(dump.localFile)) fs.unlinkSync(dump.localFile);
+            }
+        }
+        logger.info("");
+    } catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// rebase db restore <backup>
+// ─────────────────────────────────────────────────────────────────────────
+export async function restoreCommand(rawArgs: string[]): Promise<void> {
+    const args = arg(
+        {
+            "--target-db": String,
+            "--create-db": Boolean,
+            "--clean": Boolean,
+            "--no-owner": Boolean,
+            "--yes": Boolean,
+            "-y": "--yes"
+        },
+        { argv: rawArgs.slice(2), permissive: true }
+    );
+
+    const backupArg = args._[0];
+    if (!backupArg || rawArgs.includes("--help")) {
+        printRestoreHelp();
+        if (!backupArg && !rawArgs.includes("--help")) process.exit(1);
+        return;
+    }
+
+    const baseConnection = requireConnection();
+
+    // Choose the target connection: an explicit --target-db (or --create-db's
+    // implied fresh db) swaps the database name so the live one isn't clobbered.
+    const targetDb = args["--target-db"] ?? parseDbNameFromUrl(baseConnection) ?? undefined;
+    const targetConnection = args["--target-db"]
+        ? withDatabaseName(baseConnection, args["--target-db"])
+        : baseConnection;
+
+    logger.info("");
+    logger.info(chalk.bold("  ♻️  Rebase DB Restore"));
+    logger.info(chalk.gray(`  Source:  ${backupArg}`));
+    logger.info(chalk.gray(`  Target:  ${targetDb ?? "(from DATABASE_URL)"}`));
+    logger.info("");
+
+    // Resolve the local file to restore from (download object-storage keys).
+    let localFile: string;
+    let cleanupTemp = false;
+    try {
+        if (/^(s3|gs):\/\//.test(backupArg)) {
+            const dest = parseBackupDestination(backupArg.replace(/\/[^/]+$/, ""));
+            const storage = await resolveStorageForDestination(dest, process.env);
+            if (!storage) throw new BackupToolError("Could not resolve storage for the given URL.");
+            const key = backupArg.replace(/^(s3|gs):\/\/[^/]+\//, "");
+            const bucket = backupArg.replace(/^(s3|gs):\/\/([^/]+)\/.*$/, "$2");
+            const file = await storage.getObject(key, bucket);
+            if (!file) throw new BackupToolError(`Backup not found in storage: ${backupArg}`);
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "rebase-restore-"));
+            localFile = path.join(tmpDir, path.basename(key));
+            fs.writeFileSync(localFile, Buffer.from(await file.arrayBuffer()));
+            cleanupTemp = true;
+        } else {
+            localFile = path.resolve(backupArg);
+            if (!fs.existsSync(localFile)) {
+                logger.error(chalk.red(`  ✗ Backup file not found: ${localFile}`));
+                process.exit(1);
+            }
+        }
+
+        // Version pre-flight. Check against the base connection — the server
+        // version is identical for every database, and the target may not
+        // exist yet when --create-db is used.
+        const pf = await preflight("pg_restore", baseConnection);
+        if (!pf.compatible) {
+            logger.error(chalk.red(`  ✗ ${pf.reason}`));
+            process.exit(1);
+        }
+
+        // Create the target database when requested.
+        if (args["--create-db"]) {
+            if (!targetDb) {
+                logger.error(chalk.red("  ✗ --create-db requires a resolvable target database name (use --target-db)."));
+                process.exit(1);
+            }
+            const created = await ensureDatabaseExists(baseConnection, targetDb);
+            logger.info(chalk.gray(created ? `  ✓ Created database "${targetDb}".` : `  • Database "${targetDb}" already exists.`));
+        }
+
+        // Destructive-action gate. Restores overwrite data; never run without
+        // an explicit yes (interactive confirmation or --yes).
+        if (!args["--yes"]) {
+            logger.warn(chalk.yellow(
+                `  ⚠️  This will restore into "${targetDb ?? "the target database"}" and may overwrite existing data.`
+            ));
+            const confirmed = await promptConfirm(chalk.yellow("     Type 'yes' to continue: "));
+            if (!confirmed) {
+                logger.info(chalk.gray("  Aborted. No changes were made."));
+                process.exit(1);
+            }
+        }
+
+        await restoreDump({
+            connectionString: targetConnection,
+            inputFile: localFile,
+            clean: args["--clean"],
+            noOwner: args["--no-owner"],
+            inheritStdio: true
+        });
+
+        logger.info("");
+        logger.info(chalk.green(`  ✓ Restore completed into "${targetDb ?? "the target database"}".`));
+        logger.info("");
+    } catch (err) {
+        reportError(err);
+        process.exit(1);
+    } finally {
+        if (cleanupTemp && typeof localFile! === "string" && fs.existsSync(localFile!)) {
+            fs.rmSync(path.dirname(localFile!), { recursive: true, force: true });
+        }
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// rebase db backups list
+// ─────────────────────────────────────────────────────────────────────────
+export async function backupsCommand(rawArgs: string[]): Promise<void> {
+    const action = rawArgs[2];
+    if (!action || action === "--help") {
+        printBackupsHelp();
+        return;
+    }
+    if (action !== "list") {
+        logger.error(chalk.red(`Unknown backups action: "${action}". Valid: list`));
+        process.exit(1);
+    }
+
+    const args = arg({ "--out": String, "-o": "--out" }, { argv: rawArgs.slice(3), permissive: true });
+    const out = args["--out"] || process.env.BACKUP_DESTINATION || path.join(process.cwd(), "backups");
+    const dest = parseBackupDestination(out);
+
+    try {
+        const storage = await resolveStorageForDestination(dest, process.env);
+        const backups = await listBackups(dest, storage ?? undefined);
+        logger.info("");
+        if (backups.length === 0) {
+            logger.info(chalk.gray(`  No backups found at ${out}.`));
+        } else {
+            logger.info(chalk.bold(`  💾 ${backups.length} backup(s) at ${out}:`));
+            logger.info("");
+            for (const b of backups) {
+                const when = b.createdAt ? b.createdAt.toISOString() : "unknown date";
+                const name = dest.kind === "local" ? path.basename(b.key) : b.key;
+                logger.info(`  ${chalk.green("●")} ${chalk.bold(name)} ${chalk.gray(`— ${when}`)}`);
+            }
+        }
+        logger.info("");
+    } catch (err) {
+        reportError(err);
+        process.exit(1);
+    }
+}
+
+function reportError(err: unknown): void {
+    if (err instanceof BackupToolError) {
+        logger.error(chalk.red(`  ✗ ${err.message}`));
+        if (err.hint) logger.error(chalk.gray(`    ${err.hint}`));
+    } else {
+        logger.error(chalk.red(`  ✗ ${err instanceof Error ? err.message : String(err)}`));
+    }
+}
+
+function printBackupHelp(): void {
+    logger.info(`
+${chalk.bold("rebase db backup")} — Create a database backup (pg_dump, custom format)
+
+${chalk.green.bold("Usage")}
+  rebase db backup [--out <path|s3://bucket/prefix>] [options]
+
+${chalk.green.bold("Options")}
+  ${chalk.blue("--out, -o")} <dest>        Local path or s3://…/gs://… URL (default: ./backups)
+  ${chalk.blue("--exclude-schema")} <s>    Exclude a schema (repeatable)
+  ${chalk.blue("--no-owner")}              Omit ownership commands from the dump
+
+${chalk.green.bold("Notes")}
+  Backups may contain secrets and PII. Use private storage destinations and
+  enable encryption-at-rest. See docs/backups.md.
+`);
+}
+
+function printRestoreHelp(): void {
+    logger.info(`
+${chalk.bold("rebase db restore")} — Restore a database from a backup (pg_restore)
+
+${chalk.green.bold("Usage")}
+  rebase db restore <backup> [options]
+
+${chalk.green.bold("Arguments")}
+  <backup>                   Local .dump file, or s3://…/gs://… object key
+
+${chalk.green.bold("Options")}
+  ${chalk.blue("--target-db")} <name>      Restore into this database instead of DATABASE_URL's
+  ${chalk.blue("--create-db")}             Create the target database first if it doesn't exist
+  ${chalk.blue("--clean")}                 Drop existing objects before recreating them
+  ${chalk.blue("--no-owner")}              Ignore ownership from the dump
+  ${chalk.blue("--yes, -y")}               Skip the interactive confirmation ${chalk.red("(destructive!)")}
+
+${chalk.red.bold("Warning")}
+  Restore is destructive and never runs automatically. Without --yes it
+  requires an interactive 'yes'. Prefer --create-db/--target-db to restore
+  into a fresh database rather than overwriting a live one.
+`);
+}
+
+function printBackupsHelp(): void {
+    logger.info(`
+${chalk.bold("rebase db backups")} — Manage stored backups
+
+${chalk.green.bold("Usage")}
+  rebase db backups list [--out <path|s3://bucket/prefix>]
+`);
+}

package/src/backup/backup-cron.ts

@@ -0,0 +1,189 @@
+/**
+ * Scheduled backups, wired into the server cron system.
+ *
+ * A backend enables nightly (or custom-schedule) backups by dropping a cron
+ * file that default-exports {@link createBackupCron}. The heavy lifting —
+ * dump, upload, prune — reuses the same primitives as the CLI so behaviour
+ * is identical between a manual `rebase db backup` and an automated run.
+ */
+import fs from "fs";
+import type { CronJobDefinition } from "@rebasepro/types";
+import type { StorageController } from "@rebasepro/server";
+import {
+    BackupDestination,
+    parseBackupDestination,
+    parseDbNameFromUrl,
+    resolveConnectionString
+} from "./pg-tools";
+// NOTE: `./backup-service` pulls in `execa` (ESM-only). It is imported
+// lazily inside the handler so the pure `backupCronConfigFromEnv` parser can
+// be unit-tested under CommonJS without loading it.
+
+export interface BackupCronConfig {
+    /** Cron expression, e.g. `"0 3 * * *"` for 03:00 daily. */
+    schedule: string;
+    /** Postgres connection string. Defaults to `DATABASE_URL`. */
+    connectionString: string;
+    /** Where backups are written: a local path or an `s3://` / `gs://` URL. */
+    destination: BackupDestination;
+    /**
+     * Storage controller used for `s3`/`gcs` destinations. Reuse the one the
+     * backend already configured (S3/GCS/Local StorageController). Not needed
+     * for local destinations.
+     */
+    storage?: StorageController;
+    /** Delete backups older than this many days. `0` disables pruning. */
+    retentionDays?: number;
+    /** Always keep at least this many recent backups regardless of age. */
+    keepMinimum?: number;
+    /** Schemas to exclude from the dump (defaults to Atlas revision schema). */
+    excludeSchemas?: string[];
+    /** Cron job display name. */
+    name?: string;
+    /** Whether the job is enabled. */
+    enabled?: boolean;
+}
+
+export interface EnvResolution {
+    /** Resolved config, present when a schedule is configured. */
+    config?: Omit<BackupCronConfig, "storage">;
+    /** True when `BACKUP_SCHEDULE` is unset — the cron should be a no-op. */
+    disabled?: boolean;
+    /** Human-readable reason the config could not be built. */
+    error?: string;
+}
+
+/**
+ * Build backup-cron config purely from environment variables.
+ * Recognised keys:
+ *   - `BACKUP_SCHEDULE`        cron expression (required to enable)
+ *   - `BACKUP_DESTINATION`     local path or `s3://` / `gs://` URL (required)
+ *   - `BACKUP_RETENTION_DAYS`  integer days (optional)
+ *   - `BACKUP_KEEP_MINIMUM`    integer count (optional)
+ *   - `DATABASE_URL`           connection string
+ *
+ * Pure and side-effect free so it can be unit-tested without a database.
+ */
+export function backupCronConfigFromEnv(env: Record<string, string | undefined>): EnvResolution {
+    const schedule = env.BACKUP_SCHEDULE?.trim();
+    if (!schedule) {
+        return { disabled: true };
+    }
+
+    const connectionString = resolveConnectionString(env);
+    if (!connectionString) {
+        return { error: "BACKUP_SCHEDULE is set but DATABASE_URL is not configured." };
+    }
+
+    const destinationRaw = env.BACKUP_DESTINATION?.trim();
+    if (!destinationRaw) {
+        return { error: "BACKUP_SCHEDULE is set but BACKUP_DESTINATION is not configured." };
+    }
+    const destination = parseBackupDestination(destinationRaw);
+
+    const retentionDays = parseOptionalInt(env.BACKUP_RETENTION_DAYS);
+    if (retentionDays === "invalid") {
+        return { error: `BACKUP_RETENTION_DAYS must be an integer, got "${env.BACKUP_RETENTION_DAYS}".` };
+    }
+    const keepMinimum = parseOptionalInt(env.BACKUP_KEEP_MINIMUM);
+    if (keepMinimum === "invalid") {
+        return { error: `BACKUP_KEEP_MINIMUM must be an integer, got "${env.BACKUP_KEEP_MINIMUM}".` };
+    }
+
+    return {
+        config: {
+            schedule,
+            connectionString,
+            destination,
+            retentionDays: retentionDays ?? undefined,
+            keepMinimum: keepMinimum ?? undefined
+        }
+    };
+}
+
+function parseOptionalInt(value: string | undefined): number | null | "invalid" {
+    if (value === undefined || value.trim() === "") return null;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 0) return "invalid";
+    return n;
+}
+
+/**
+ * Create a {@link CronJobDefinition} that dumps the database, uploads the
+ * result to the configured destination, and prunes old backups. Object
+ * destinations require {@link BackupCronConfig.storage}.
+ */
+export function createBackupCron(config: BackupCronConfig): CronJobDefinition {
+    const dbName = parseDbNameFromUrl(config.connectionString) ?? "database";
+    const excludeSchemas = config.excludeSchemas ?? ["rebase"];
+
+    return {
+        name: config.name ?? "Scheduled database backup",
+        schedule: config.schedule,
+        description: "Dumps the Postgres database and uploads it to the configured backup destination.",
+        enabled: config.enabled ?? true,
+        // Backups of a large database can take a while; allow up to an hour.
+        timeoutSeconds: 3600,
+        async handler({ log }) {
+            const { createDump, pruneBackups, uploadBackup } = await import("./backup-service");
+            const { destination } = config;
+
+            if (destination.kind !== "local" && !config.storage) {
+                throw new Error(
+                    `Backup destination is ${destination.kind} but no storage controller was provided. ` +
+                    "Pass the backend's configured StorageController to createBackupCron({ storage })."
+                );
+            }
+
+            log(`Starting backup of "${dbName}"…`);
+            const outDir = destination.kind === "local" ? destination.path : undefined;
+            const dump = await createDump({
+                connectionString: config.connectionString,
+                dbName,
+                outDir,
+                excludeSchemas
+            });
+            log(`Dump created: ${dump.fileName} (${formatBytes(dump.sizeBytes)})`);
+
+            let storedKey = dump.localFile;
+            try {
+                if (destination.kind !== "local") {
+                    const uploaded = await uploadBackup(config.storage!, dump.localFile, destination);
+                    storedKey = uploaded.storageUrl;
+                    log(`Uploaded to ${uploaded.storageUrl}`);
+                }
+            } finally {
+                // For object-storage destinations the local dump was a temp
+                // file — remove it once uploaded (or on failure).
+                if (destination.kind !== "local" && fs.existsSync(dump.localFile)) {
+                    fs.unlinkSync(dump.localFile);
+                }
+            }
+
+            let pruned: string[] = [];
+            if (config.retentionDays && config.retentionDays > 0) {
+                pruned = await pruneBackups(
+                    destination,
+                    { retentionDays: config.retentionDays, keepMinimum: config.keepMinimum },
+                    config.storage
+                );
+                if (pruned.length > 0) {
+                    log(`Pruned ${pruned.length} backup(s) older than ${config.retentionDays} day(s).`);
+                }
+            }
+
+            return {
+                backup: storedKey,
+                sizeBytes: dump.sizeBytes,
+                pruned: pruned.length
+            };
+        }
+    };
+}
+
+function formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}