@rebasepro/server-postgres 0.25.0 → 0.26.0

package/dist/{backup-service-Bb39plam.js → backup-cli-PoRG-zEq.js}

@@ -1,11 +1,14 @@
 import { createRequire as __createRequire } from "module";
 __createRequire(import.meta.url);
-import { n as __exportAll } from "./rolldown-runtime-V7rFbMRe.js";
-import { $ as forLibpq, tt as splitPassword, z as resolveLocalBin } from "./cli-errors-DwQnNATs.js";
-import { o as execa } from "./rls-bootstrap-sql-Bd-hJk08.js";
+import { i as __exportAll, t as promptConfirm } from "./cli-prompt-DXG0yk-h.js";
+import { et as forLibpq, nt as splitPassword, t as checkDatabaseConnectivity, tt as redactConnectionPasswords, z as resolveLocalBin } from "./cli-errors-DsYyNYzd.js";
+import { a as outWarn, i as outError, r as out, t as chalk } from "./source-fZb92pN8.js";
+import { T as execa, _ as parseCommandFlags, h as closestWord } from "./migrate-baseline-B-2Ef4Mv.js";
 import path from "path";
 import fs from "fs";
 import os from "os";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
 //#region src/backup/pg-tools.ts
 /**
 * Pure helpers for the backup/restore commands.
@@ -559,6 +562,7 @@ var backup_service_exports = /* @__PURE__ */ __exportAll({
 	CleanRestoreFailed: () => CleanRestoreFailed,
 	applyGlobals: () => applyGlobals,
 	createDump: () => createDump,
+	describeUnreadableDump: () => describeUnreadableDump,
 	detectToolMajor: () => detectToolMajor,
 	discardPartialDump: () => discardPartialDump,
 	ensureDatabaseExists: () => ensureDatabaseExists,
@@ -1054,11 +1058,47 @@ async function readDumpObjects(inputFile, env = process.env) {
 	const bin = resolvePgBinary("pg_restore", env);
 	if (!bin) throw new BackupToolError("Could not find the 'pg_restore' binary.", "Install the PostgreSQL client tools or set PG_RESTORE_PATH.");
 	const toolEnv = Object.fromEntries(Object.entries(env).filter((entry) => entry[1] !== void 0));
-	const { stdout } = await execa(bin, buildPgRestoreListArgs(inputFile), {
-		stdio: "pipe",
-		env: toolEnv
-	});
-	return parseDumpObjects(stdout);
+	let listed;
+	try {
+		({stdout: listed} = await execa(bin, buildPgRestoreListArgs(inputFile), {
+			stdio: "pipe",
+			env: toolEnv
+		}));
+	} catch (err) {
+		const stderr = err instanceof Error && "stderr" in err && typeof err.stderr === "string" ? err.stderr : "";
+		const { message, hint } = describeUnreadableDump(path.basename(inputFile), stderr);
+		throw new BackupToolError(message, hint);
+	}
+	return parseDumpObjects(listed);
+}
+/**
+* What `db restore` says of a file whose table of contents pg_restore cannot
+* read: before anything is restored, so nothing has changed.
+*
+* `pgRestoreStderr` is what `pg_restore --list` printed. Its first error line
+* is quoted, so the reader sees the tool's own words too.
+*/
+function describeUnreadableDump(file, pgRestoreStderr) {
+	const said = pgRestoreStderr.split("\n").map((line) => line.replace(/^pg_restore:\s*(?:error:\s*)?/, "").trim()).find((line) => line.length > 0);
+	const quoted = said ? ` (pg_restore: ${said})` : "";
+	const unchanged = "Nothing was restored or changed.";
+	const elsewhere = "Restore from another backup (`rebase db backups list` lists them), or copy this one again from where it came from.";
+	if (said && /unsupported version \(([\d.]+)\) in file header/.test(said)) return {
+		message: `${file} was written by a newer pg_dump than this pg_restore reads${quoted}. ${unchanged}`,
+		hint: "Install the PostgreSQL client tools of the version that wrote it, or set PG_RESTORE_PATH to that pg_restore."
+	};
+	if (said && /does not appear to be a valid archive/.test(said)) return {
+		message: `${file} is not a backup pg_restore can read${quoted}. \`rebase db restore\` takes the .dump files \`rebase db backup\` writes. ${unchanged}`,
+		hint: elsewhere
+	};
+	if (said && /end of file|too short/.test(said)) return {
+		message: `${file} is truncated: it ends before pg_restore can read what it holds${quoted}. A copy or download that did not finish, or a disk that filled while it was written, leaves a file like this. Nothing was restored or changed.`,
+		hint: elsewhere
+	};
+	return {
+		message: `${file} cannot be read as a backup${quoted}: it is damaged, or not a pg_dump archive. ${unchanged}`,
+		hint: elsewhere
+	};
 }
 /**
 * Which of a dump's schemas and tables the target database already holds,
@@ -1189,6 +1229,733 @@ async function pruneBackups(dest, options, storage) {
 	return toDelete;
 }
 //#endregion
-export { buildPgRestoreScriptArgs as A, parseDbNameFromUrl as B, selectBackupsToPrune as C, buildPgDumpallGlobalsArgs as D, buildPgDumpArgs as E, diagnoseRowSecurityDumpFailure as F, splitGlobalsStatements as G, parsePgToolMajor as H, globalsFileForDump as I, withDatabaseName as K, joinStorageKey as L, buildRowSecurityPgOptions as M, checkToolServerCompatibility as N, buildPgRestoreArgs as O, cleanRestorePrelude as P, parseBackupDestination as R, resolvePgBinary as S, buildBackupFilename as T, resolveConnectionString as U, parseDumpObjects as V, serverVersionNumToMajor as W, restoreDump as _, createDump as a, validateDump as b, ensureDatabaseExists as c, getServerVersionMajor as d, listBackups as f, resetSharedSession as g, readDumpObjects as h, backup_service_exports as i, buildPsqlScriptArgs as j, buildPgRestoreListArgs as k, findCleanExtras as l, pruneBackups as m, CleanRestoreFailed as n, detectToolMajor as o, preflight as p, applyGlobals as r, discardPartialDump as s, BackupToolError as t, findRestoreConflicts as u, restoreDumpReplacing as v, CLEAN_LOCK_TIMEOUT as w, pgToolVariable as x, uploadBackup as y, parseBackupTimestamp as z };
+//#region src/backup/backup-cli.ts
+var backup_cli_exports = /* @__PURE__ */ __exportAll({
+	INVOCATION_CWD_ENV: () => INVOCATION_CWD_ENV,
+	backupCommand: () => backupCommand,
+	backupsCommand: () => backupsCommand,
+	confirmRestore: () => confirmRestore,
+	describeCleanExtras: () => describeCleanExtras,
+	describeCleanRestoreFailure: () => describeCleanRestoreFailure,
+	describeRestoreConflict: () => describeRestoreConflict,
+	excludesRebaseSchema: () => excludesRebaseSchema,
+	invocationDir: () => invocationDir,
+	parseBackupLine: () => parseBackupLine,
+	parseBackupsListLine: () => parseBackupsListLine,
+	parseRestoreLine: () => parseRestoreLine,
+	resolveBackupLocation: () => resolveBackupLocation,
+	resolveStorageForDestination: () => resolveStorageForDestination,
+	restoreCommand: () => restoreCommand,
+	schemaPatternRegex: () => schemaPatternRegex,
+	unknownBackupsAction: () => unknownBackupsAction
+});
+function formatBytes(bytes) {
+	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`;
+}
+/** A web stream's chunks, for piping into a file. */
+async function* webChunks(stream) {
+	const reader = stream.getReader();
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) return;
+			yield value;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+/**
+* The controller for an object-storage destination, or `null` for a local one.
+*
+* Built by `backupStorageFromEnv` from `@rebasepro/server` — the function the
+* Backups panel's routes use — so the CLI and the panel read a bucket the same
+* way. This file had its own copy, and the two had already drifted once
+* (`S3_FORCE_PATH_STYLE` read as `=== "true"`, so a MinIO backup addressed the
+* bucket as a host).
+*
+* Exported for its test.
+*/
+async function resolveStorageForDestination(dest, env) {
+	if (dest.kind === "local") return null;
+	const { backupStorageFromEnv } = await import("@rebasepro/server");
+	try {
+		return backupStorageFromEnv(dest, env);
+	} catch (error) {
+		throw new BackupToolError(error instanceof Error ? error.message : String(error), "Set the same S3_* variables your backend uses for storage.");
+	}
+}
+/**
+* The directory `rebase` was run from, which `rebase` puts here for the driver.
+*
+* The driver runs in the project's `backend/`, so a relative path resolved
+* against its own working directory named a different place from the one the
+* user typed it in: `rebase db backup --out ./backups` wrote to `<root>/backups`
+* (the CLI resolves explicit paths itself) while `rebase db backups list`
+* looked in `<root>/backend/backups`. Spelled the same in
+* `packages/cli/src/commands/db.ts`.
+*/
+var INVOCATION_CWD_ENV = "REBASE_INVOCATION_CWD";
+/** Where a relative path the user typed is relative to: where they ran `rebase`. */
+function invocationDir(env = process.env) {
+	const dir = env[INVOCATION_CWD_ENV]?.trim();
+	return dir && path.isAbsolute(dir) ? dir : process.cwd();
+}
+/**
+* Where `db backup` writes and `db backups list` reads, by one rule.
+*
+* - `--out` is relative to where `rebase` was run, like any path typed on a
+*   command line.
+* - `BACKUP_DESTINATION` is relative to the backend directory, because the
+*   server reads the same variable there: the Backups panel and the scheduled
+*   backup have to find what the CLI wrote.
+* - With neither, `./backups` where `rebase` was run, as the help says.
+*
+* An `s3://` or `gs://` destination is returned as given.
+*/
+function resolveBackupLocation(opts) {
+	const flag = opts.flag?.trim();
+	if (flag) return isRemoteDestination(flag) ? flag : path.resolve(opts.invocationDir, flag);
+	const configured = opts.configured?.trim();
+	if (configured) return isRemoteDestination(configured) ? configured : path.resolve(opts.backendDir, configured);
+	return path.join(opts.invocationDir, "backups");
+}
+function isRemoteDestination(value) {
+	return parseBackupDestination(value).kind !== "local";
+}
+/** {@link resolveBackupLocation} for this process. */
+function backupLocation(flag) {
+	return resolveBackupLocation({
+		flag,
+		configured: process.env.BACKUP_DESTINATION,
+		invocationDir: invocationDir(),
+		backendDir: process.cwd()
+	});
+}
+function requireConnection() {
+	const conn = resolveConnectionString(process.env);
+	if (!conn) {
+		outError(chalk.red("✗ DATABASE_URL is not set. Make sure your .env file is configured."));
+		process.exit(1);
+	}
+	return conn;
+}
+var BACKUP_FLAGS = {
+	"--out": String,
+	"--output": "--out",
+	"--exclude-schema": [String],
+	"--no-owner": Boolean,
+	"--enable-row-security": Boolean,
+	"--row-security-role": String,
+	"-o": "--out"
+};
+/**
+* Parse a `rebase db backup …` line. An undeclared flag is refused (see
+* `parseCommandFlags`), and so is a positional: `rebase db backup ./backups`
+* means `--out ./backups`, and taken as nothing it wrote to the default
+* directory.
+*/
+function parseBackupLine(rawArgs) {
+	const args = parseCommandFlags(BACKUP_FLAGS, rawArgs.slice(2), "db backup");
+	const [typed] = args._;
+	if (typed !== void 0) {
+		const stray = redactConnectionPasswords(typed);
+		throw new Error(`\`rebase db backup\` takes no argument "${stray}". Nothing was run. To choose where the backup goes, pass --out ${stray}.`);
+	}
+	const dropsRebase = (args["--exclude-schema"] ?? []).find(excludesRebaseSchema);
+	if (dropsRebase !== void 0) throw new Error(excludesRebaseMessage(dropsRebase));
+	return args;
+}
+/**
+* A `pg_dump --exclude-schema` pattern as the regular expression pg_dump
+* hands the server, by pg_dump's own rules (`patternToSQLRegex` in
+* PostgreSQL's `fe_utils/string_utils.c`):
+*
+* - outside double quotes, an upper-case letter is folded to lower case, `*`
+*   is `.*`, `?` is `.`, and every other character, regular-expression syntax
+*   included (`[r]`, `(a|b)`, `+`), passes through as it is;
+* - inside double quotes, case is kept and every special character is
+*   matched literally; `""` is one quote;
+* - `$` is always literal, and `[]` is always the two characters;
+* - an unquoted `.` separates a database from the schema, so `shop.rebase`
+*   is matched on `rebase`.
+*
+* The result is anchored, as pg_dump anchors it: `^(…)$`.
+*/
+function schemaPatternRegex(pattern) {
+	let regex = "";
+	let inQuotes = false;
+	for (let index = 0; index < pattern.length; index += 1) {
+		const char = pattern[index];
+		if (char === "\"") if (inQuotes && pattern[index + 1] === "\"") {
+			regex += "\"";
+			index += 1;
+		} else inQuotes = !inQuotes;
+		else if (!inQuotes && char >= "A" && char <= "Z") regex += char.toLowerCase();
+		else if (!inQuotes && char === "*") regex += ".*";
+		else if (!inQuotes && char === "?") regex += ".";
+		else if (!inQuotes && char === ".") regex = "";
+		else if (char === "$") regex += "\\$";
+		else if (inQuotes && "|*+?()[]{}.^$\\".includes(char)) regex += `\\${char}`;
+		else if (char === "[" && pattern[index + 1] === "]") regex += "\\[";
+		else regex += char;
+	}
+	return `^(${regex})$`;
+}
+/**
+* Whether a `pg_dump --exclude-schema` pattern matches the `rebase` schema, by
+* pg_dump's own rules (see {@link schemaPatternRegex}).
+*
+* Evaluated here with JavaScript's regular expressions, which read the syntax
+* people write in a pattern (`[r]ebase`, `(rebase|x)`, `reb.+`) as the
+* server does. The server's engine has syntax JavaScript reads otherwise
+* (`[[:alpha:]]`, `\m`), so `db backup` asks the server too before it dumps
+* (see `backupCommand`); this check is the one that answers before anything
+* connects. A pattern JavaScript cannot compile is left to that one.
+*/
+function excludesRebaseSchema(pattern) {
+	try {
+		return new RegExp(schemaPatternRegex(pattern)).test("rebase");
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether the server's regular-expression engine matches `name` with `regex`,
+* the way pg_dump's own query matches a schema pattern
+* (`nspname OPERATOR(pg_catalog.~) '^(…)$' COLLATE pg_catalog.default`).
+*
+* A regex the server will not compile matches nothing here; pg_dump then
+* refuses it in its own words.
+*/
+async function serverRegexMatches(connectionString, regex, name) {
+	const { Client } = await import("pg");
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		const { rows } = await client.query("SELECT $1::text OPERATOR(pg_catalog.~) $2::text COLLATE pg_catalog.default AS matches", [name, regex]);
+		return rows[0]?.matches === true;
+	} catch (err) {
+		if (err instanceof Error && "code" in err && err.code === "2201B") return false;
+		throw err;
+	} finally {
+		await client.end();
+	}
+}
+/** The refusal for a pattern that leaves out the rebase schema. */
+function excludesRebaseMessage(pattern) {
+	return `--exclude-schema ${pattern} leaves out the rebase schema, and a backup without it cannot be restored: it holds the users, roles and the functions every policy calls. Nothing was run.`;
+}
+async function backupCommand(rawArgs) {
+	if (rawArgs.includes("--help")) {
+		printBackupHelp();
+		return;
+	}
+	const args = parseBackupLine(rawArgs);
+	const connectionString = requireConnection();
+	const dbName = parseDbNameFromUrl(connectionString) ?? "database";
+	const out$1 = backupLocation(args["--out"]);
+	const dest = parseBackupDestination(out$1);
+	out("");
+	out(chalk.bold("  💾 Rebase DB Backup"));
+	out(chalk.gray(`  Database:    ${dbName}`));
+	out(chalk.gray(`  Destination: ${out$1}`));
+	out("");
+	await checkDatabaseConnectivity(connectionString);
+	for (const pattern of args["--exclude-schema"] ?? []) if (await serverRegexMatches(connectionString, schemaPatternRegex(pattern), "rebase")) {
+		outError(chalk.red(`  ✗ ${excludesRebaseMessage(pattern)}`));
+		process.exit(1);
+	}
+	const pf = await preflight("pg_dump", connectionString);
+	if (!pf.compatible) {
+		outError(chalk.red(`  ✗ ${pf.reason}`));
+		process.exit(1);
+	}
+	out(chalk.gray(`  Using pg_dump ${pf.toolMajor} against server ${pf.serverMajor}.`));
+	const rowSecurity = args["--enable-row-security"] ? {
+		uid: "rebase-db-backup",
+		roles: [args["--row-security-role"] || "admin"]
+	} : void 0;
+	if (rowSecurity) {
+		outWarn("");
+		outWarn(chalk.yellow("  ⚠  Dumping with row-level security ON."));
+		outWarn(chalk.gray(`     Reading as roles [${rowSecurity.roles.join(", ")}], which satisfies the generated`));
+		outWarn(chalk.gray("     `admin_full_access` policy. This backup contains exactly the rows those"));
+		outWarn(chalk.gray("     policies admit — a table whose policies have no admin rule comes out short,"));
+		outWarn(chalk.gray("     and pg_dump will not say so. Prefer granting the dumping role BYPASSRLS."));
+		outWarn("");
+	}
+	try {
+		if (dest.kind === "local") {
+			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) : void 0,
+				excludeSchemas: args["--exclude-schema"],
+				noOwner: args["--no-owner"],
+				inheritStdio: true,
+				rowSecurity
+			});
+			await assertDumpValid(dump.localFile);
+			out("");
+			out(chalk.green(`  ✓ Backup written to ${dump.localFile} (${formatBytes(dump.sizeBytes)})`));
+			if (dump.globalsFile) out(chalk.gray(`    ✓ Roles captured to ${dump.globalsFile} (needed so RLS survives a restore).`));
+		} else {
+			const storage = await resolveStorageForDestination(dest, process.env);
+			const dump = await createDump({
+				connectionString,
+				dbName,
+				excludeSchemas: args["--exclude-schema"],
+				noOwner: args["--no-owner"],
+				inheritStdio: true,
+				rowSecurity
+			});
+			try {
+				await assertDumpValid(dump.localFile);
+				const uploaded = await uploadBackup(storage, dump.localFile, dest);
+				out("");
+				out(chalk.green(`  ✓ Backup uploaded to ${uploaded.storageUrl} (${formatBytes(dump.sizeBytes)})`));
+				if (dump.globalsFile && fs.existsSync(dump.globalsFile)) {
+					const globalsUpload = await uploadBackup(storage, dump.globalsFile, dest);
+					out(chalk.gray(`    ✓ Roles uploaded to ${globalsUpload.storageUrl} (needed so RLS survives a restore).`));
+				}
+				out(chalk.gray("    Ensure this bucket is private — backups may contain secrets and PII."));
+			} finally {
+				if (fs.existsSync(dump.localFile)) fs.unlinkSync(dump.localFile);
+				if (dump.globalsFile && fs.existsSync(dump.globalsFile)) fs.unlinkSync(dump.globalsFile);
+			}
+		}
+		out("");
+	} catch (err) {
+		reportError(err);
+		process.exit(1);
+	}
+}
+var RESTORE_FLAGS = {
+	"--target-db": String,
+	"--create-db": Boolean,
+	"--clean": Boolean,
+	"--no-owner": Boolean,
+	"--continue-on-error": Boolean,
+	"--yes": Boolean,
+	"-y": "--yes"
+};
+/**
+* Parse a `rebase db restore …` line; the one positional is the backup.
+*
+* Strict, because this is the command where a typo costs most: parsed
+* permissively, `--targt-db x` became a second positional, the target fell
+* back to DATABASE_URL's own database, and the restore ran against the live
+* one.
+*/
+function parseRestoreLine(rawArgs) {
+	const args = parseCommandFlags(RESTORE_FLAGS, rawArgs.slice(2), "db restore");
+	if (args._.length > 1) throw new Error(`\`rebase db restore\` restores one backup, and was given ${args._.length}: ${args._.map((word) => `"${redactConnectionPasswords(word)}"`).join(", ")}. Nothing was run.`);
+	return args;
+}
+/**
+* The restore's one question, asked before anything can change.
+*
+* `--yes` skips it. On a terminal it asks for a typed 'yes'. With no terminal
+* nobody can answer, and the refusal says to pass `--yes`, as `db reset`,
+* `db pull` and `db branch prune` do: "Aborted. No changes were made." alone
+* read as though someone had answered no.
+*
+* @returns whether to go on. When not, it has said why.
+*/
+async function confirmRestore(opts) {
+	if (opts.yes) return true;
+	outWarn(chalk.yellow(`  ⚠️  This will restore into "${opts.target}" and may overwrite existing data.`));
+	if (!opts.interactive) {
+		outError(chalk.red("  ✗ Nothing was restored: there is no terminal to confirm on."));
+		outError(chalk.gray(`    Re-run with --yes to restore into "${opts.target}".`));
+		return false;
+	}
+	const confirmed = await opts.ask(chalk.yellow("     Type 'yes' to continue: "));
+	if (!confirmed) out(chalk.gray("  Aborted. No changes were made."));
+	return confirmed;
+}
+/** How many of the conflicting objects a refusal names before counting the rest. */
+var CONFLICTS_NAMED = 5;
+/**
+* What `db restore` says when the target already holds what the backup
+* creates, and the two ways round it: `--clean` replaces them with the
+* backup's copy, a new database restores beside them.
+*
+* `line` is the rest of what the user typed — the database it names, `--yes`,
+* `--no-owner` — which both commands keep, so the one copied runs against the
+* same database and does not stop again to ask. `--target-db` goes on the
+* `--clean` one only: the other names a new database.
+*/
+function describeRestoreConflict(target, backupArg, conflicts, line = {}) {
+	const named = conflicts.slice(0, CONFLICTS_NAMED).join(", ");
+	const more = conflicts.length > CONFLICTS_NAMED ? `, and ${conflicts.length - CONFLICTS_NAMED} more` : "";
+	const carried = line.carried?.length ? ` ${line.carried.join(" ")}` : "";
+	const sameTarget = line.targetDb ? ` --target-db ${line.targetDb}` : "";
+	return {
+		message: `"${target}" already holds ${named}${more}, which this backup creates. Without --clean, pg_restore stops at the first of them. Nothing was restored or changed.`,
+		hint: [`To replace them with the backup's copy:  rebase db restore ${backupArg}${sameTarget} --clean${carried}`, `To restore beside them, in a new database:  rebase db restore ${backupArg} --create-db --target-db <new name>${carried}`].join("\n    ")
+	};
+}
+/** How many of the objects `--clean` drops beyond the backup's own it names before counting the rest. */
+var EXTRAS_NAMED = 10;
+/**
+* What `restore --clean` says, before it asks, about what it drops that the
+* backup does not hold — see `findCleanExtras`. Nothing when there is none.
+*/
+function describeCleanExtras(schemas, extras) {
+	if (extras.length === 0) return [];
+	const replaced = schemas.filter((schema) => schema !== "public");
+	return [
+		replaced.length > 0 ? `--clean replaces ${replaced.length === 1 ? "schema" : "schemas"} ${replaced.join(", ")} whole, so it also drops what this backup does not hold:` : "--clean also drops what this backup does not hold:",
+		...extras.slice(0, EXTRAS_NAMED).map((extra) => `  ${extra}`),
+		...extras.length > EXTRAS_NAMED ? [`  and ${extras.length - EXTRAS_NAMED} more`] : []
+	];
+}
+/**
+* What a `restore --clean` that stopped says: it ran as one transaction, so
+* nothing changed. The cluster roles the sidecar recreated are the exception,
+* and are said to be.
+*/
+function describeCleanRestoreFailure(target, failure, rolesApplied) {
+	const why = failure.tool === "pg_restore" ? "pg_restore could not read the whole backup" : failure.lockTimeout ? `it waited too long for a lock on "${target}"` : "a statement failed";
+	const hints = [...failure.lockTimeout ? ["Something holds a lock on it — usually a `rebase dev` serving from it. Stop that, then restore again."] : [], ...rolesApplied > 0 ? [`The ${rolesApplied} cluster role(s) recreated from the backup's sidecar before it stay.`] : []];
+	return {
+		message: `Nothing was restored or changed: the restore ran as one transaction, and it was rolled back when ${why} (above). "${target}" holds what it held before.`,
+		hint: hints.length > 0 ? hints.join("\n    ") : void 0
+	};
+}
+async function restoreCommand(rawArgs) {
+	if (rawArgs.includes("--help")) {
+		printRestoreHelp();
+		return;
+	}
+	const args = parseRestoreLine(rawArgs);
+	const backupArg = args._[0];
+	if (!backupArg) {
+		printRestoreHelp();
+		process.exit(1);
+	}
+	const baseConnection = requireConnection();
+	const targetDb = args["--target-db"] ?? parseDbNameFromUrl(baseConnection) ?? void 0;
+	const targetConnection = args["--target-db"] ? withDatabaseName(baseConnection, args["--target-db"]) : baseConnection;
+	out("");
+	out(chalk.bold("  ♻️  Rebase DB Restore"));
+	out(chalk.gray(`  Source:  ${backupArg}`));
+	out(chalk.gray(`  Target:  ${targetDb ?? "(from DATABASE_URL)"}`));
+	out("");
+	await checkDatabaseConnectivity(baseConnection);
+	let localFile;
+	let globalsSql = null;
+	let cleanupTemp = false;
+	try {
+		if (/^(s3|gs):\/\//.test(backupArg)) {
+			const storage = await resolveStorageForDestination(parseBackupDestination(backupArg.replace(/\/[^/]+$/, "")), 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 tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "rebase-restore-"));
+			localFile = path.join(tmpDir, path.basename(key));
+			cleanupTemp = true;
+			const object = storage.getObjectStream ? await storage.getObjectStream(key, { bucket }) : await storage.getObject(key, bucket).then((file) => file && { stream: file.stream() });
+			if (!object) throw new BackupToolError(`Backup not found in storage: ${backupArg}`);
+			await pipeline(Readable.from(webChunks(object.stream)), fs.createWriteStream(localFile));
+			const globalsObj = await storage.getObject(globalsFileForDump(key), bucket);
+			if (globalsObj) globalsSql = Buffer.from(await globalsObj.arrayBuffer()).toString("utf-8");
+		} else {
+			localFile = path.resolve(invocationDir(), backupArg);
+			if (!fs.existsSync(localFile)) throw new BackupToolError(`Backup file not found: ${localFile}`);
+			const globalsPath = globalsFileForDump(localFile);
+			if (fs.existsSync(globalsPath)) globalsSql = fs.readFileSync(globalsPath, "utf-8");
+		}
+		const pf = await preflight("pg_restore", baseConnection);
+		if (!pf.compatible) throw new BackupToolError(pf.reason ?? "pg_restore cannot restore into this server.");
+		if (args["--create-db"] && !targetDb) throw new BackupToolError("--create-db requires a resolvable target database name (use --target-db).");
+		const objects = await readDumpObjects(localFile);
+		if (!args["--clean"]) {
+			const conflicts = await findRestoreConflicts(targetConnection, objects);
+			if (conflicts.length > 0) {
+				const { message, hint } = describeRestoreConflict(targetDb ?? "the target database", backupArg, conflicts, {
+					targetDb: args["--target-db"],
+					carried: [
+						...args["--database-url"] ? ["--database-url", `"${args["--database-url"]}"`] : [],
+						...args["--docker"] ? ["--docker"] : [],
+						...args["--no-owner"] ? ["--no-owner"] : [],
+						...args["--yes"] ? ["--yes"] : []
+					]
+				});
+				throw new BackupToolError(message, hint);
+			}
+		}
+		const replacing = args["--clean"] === true && args["--continue-on-error"] !== true;
+		if (replacing) {
+			if (!resolvePgBinary("psql")) throw new BackupToolError("Could not find the 'psql' binary, which runs a --clean restore as one transaction. Nothing was restored or changed.", "Install the PostgreSQL client tools (they ship psql beside pg_restore), or set PSQL_PATH to its full path.");
+			const extras = describeCleanExtras(objects.schemas, await findCleanExtras(targetConnection, objects));
+			if (extras.length > 0) {
+				outWarn(chalk.yellow(`  ⚠️  ${extras[0]}`));
+				for (const extra of extras.slice(1)) outWarn(chalk.yellow(`     ${extra}`));
+			}
+		}
+		if (!await confirmRestore({
+			target: targetDb ?? "the target database",
+			yes: args["--yes"] === true,
+			interactive: process.stdin.isTTY === true,
+			ask: promptConfirm
+		})) {
+			process.exitCode = 1;
+			return;
+		}
+		if (args["--create-db"]) {
+			const created = await ensureDatabaseExists(baseConnection, targetDb);
+			out(chalk.gray(created ? `  ✓ Created database "${targetDb}".` : `  • Database "${targetDb}" already exists.`));
+		}
+		let rolesApplied = 0;
+		if (globalsSql) {
+			out(chalk.gray("  Recreating cluster roles from the backup's roles sidecar…"));
+			const { applied, skipped } = await applyGlobals(targetConnection, globalsSql, (m) => out(chalk.gray(m)));
+			rolesApplied = applied;
+			out(chalk.gray(`  ✓ Roles: ${applied} applied, ${skipped} skipped (already present or not permitted).`));
+		} else {
+			outWarn(chalk.yellow("  ⚠️  No roles sidecar (.globals.sql) accompanies this backup."));
+			outWarn(chalk.yellow("     If the dump grants to roles that don't exist (e.g. rebase_user), the restore"));
+			outWarn(chalk.yellow("     will fail — recreate those roles first, or use a backup that includes its globals."));
+		}
+		try {
+			if (replacing) await restoreDumpReplacing({
+				connectionString: targetConnection,
+				inputFile: localFile,
+				objects,
+				noOwner: args["--no-owner"],
+				inheritStdio: true
+			});
+			else await restoreDump({
+				connectionString: targetConnection,
+				inputFile: localFile,
+				clean: args["--clean"],
+				noOwner: args["--no-owner"],
+				exitOnError: !args["--continue-on-error"],
+				inheritStdio: true
+			});
+		} catch (err) {
+			if (err instanceof BackupToolError) throw err;
+			if (err instanceof CleanRestoreFailed) {
+				const { message, hint } = describeCleanRestoreFailure(targetDb ?? "the target database", err, rolesApplied);
+				throw new BackupToolError(message, hint);
+			}
+			throw new BackupToolError(`pg_restore stopped on the error above. What it restored before that stays in "${targetDb ?? "the target database"}".`, rolesApplied > 0 ? `The ${rolesApplied} cluster role(s) recreated from the backup's sidecar before it stay too.` : void 0);
+		}
+		out("");
+		out(chalk.green(`  ✓ Restore completed into "${targetDb ?? "the target database"}".`));
+		out("");
+	} catch (err) {
+		reportError(err);
+		process.exitCode = 1;
+	} finally {
+		if (cleanupTemp && typeof localFile === "string" && fs.existsSync(localFile)) fs.rmSync(path.dirname(localFile), {
+			recursive: true,
+			force: true
+		});
+	}
+}
+var BACKUPS_ACTIONS = ["list"];
+var BACKUPS_LIST_FLAGS = {
+	"--out": String,
+	"--output": "--out",
+	"-o": "--out"
+};
+/**
+* Parse a `rebase db backups list …` line, or its `rebase db backup list …`
+* spelling: the flags start after `list`, the third word of either.
+*/
+function parseBackupsListLine(rawArgs) {
+	return parseCommandFlags(BACKUPS_LIST_FLAGS, rawArgs.slice(3), "db backups list");
+}
+/** What `db backups <action>` says of an action it does not have: the sentence every `db` command says. */
+function unknownBackupsAction(action) {
+	const near = closestWord(action, BACKUPS_ACTIONS);
+	return near ? `Unknown db backups command "${action}" — did you mean \`${near}\`? Run \`rebase db backups --help\` for the rest.` : `Unknown db backups command "${action}". Run \`rebase db backups --help\` for the ones there are.`;
+}
+async function backupsCommand(rawArgs) {
+	const action = rawArgs[2];
+	if (!action || action === "--help") {
+		printBackupsHelp();
+		return;
+	}
+	if (action !== "list") {
+		outError(chalk.red(`✗ ${unknownBackupsAction(action)}`));
+		process.exit(1);
+	}
+	const args = parseBackupsListLine(rawArgs);
+	const out$2 = backupLocation(args["--out"]);
+	const dest = parseBackupDestination(out$2);
+	try {
+		const backups = await listBackups(dest, await resolveStorageForDestination(dest, process.env) ?? void 0);
+		out("");
+		if (backups.length === 0) {
+			out(chalk.gray(`  No backups found at ${out$2}.`));
+			await mentionBackendBackups(out$2, args["--out"]);
+		} else {
+			out(chalk.bold(`  💾 ${backups.length} backup(s) at ${out$2}:`));
+			out("");
+			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;
+				const empty = b.sizeBytes === 0;
+				const size = b.sizeBytes === void 0 ? "" : ` — ${formatBytes(b.sizeBytes)}`;
+				if (empty) out(`  ${chalk.red("○")} ${chalk.bold(name)} ${chalk.gray(`— ${when}`)}${chalk.red(" — EMPTY, not restorable")}`);
+				else out(`  ${chalk.green("●")} ${chalk.bold(name)} ${chalk.gray(`— ${when}${size}`)}`);
+			}
+			if (backups.some((b) => b.sizeBytes === 0)) {
+				out("");
+				out(chalk.yellow("  ⚠  Empty files above are leftovers from a failed backup. Delete them:"));
+				out(chalk.gray("     they count as recent backups for retention but restore nothing."));
+			}
+		}
+		out("");
+	} catch (err) {
+		reportError(err);
+		process.exit(1);
+	}
+}
+/**
+* Point at `<backend>/backups` when the default listing is empty and that
+* directory holds dumps.
+*
+* Earlier releases resolved the default there, so after an upgrade the
+* backups a project already has are one directory away from the listing.
+*/
+async function mentionBackendBackups(listed, flag) {
+	if (flag || process.env.BACKUP_DESTINATION?.trim()) return;
+	const backendBackups = path.join(process.cwd(), "backups");
+	if (path.resolve(listed) === backendBackups) return;
+	const found = await listBackups({
+		kind: "local",
+		path: backendBackups
+	}).catch(() => []);
+	if (found.length === 0) return;
+	out(chalk.gray(`  ${found.length} backup(s) are in ${backendBackups}, where earlier releases of`));
+	out(chalk.gray(`  \`rebase db backup\` wrote by default. List them with:`));
+	out(chalk.gray(`    rebase db backups list --out ${path.relative(invocationDir(), backendBackups) || "."}`));
+}
+/**
+* Verify a freshly written dump; abort the command if it looks corrupt.
+*
+* Discards the artifact on the way out. Refusing to *report* success was never
+* enough on its own: the file stayed on disk, `rebase db backups list` showed
+* it as an ordinary entry, and retention — which ranks by timestamp and never
+* looks at size — would protect it as one of the `keepMinimum` newest while
+* pruning a real backup underneath it. The roles sidecar goes too; the two are
+* uploaded and pruned as a pair, so half a pair is not a backup either.
+*/
+async function assertDumpValid(localFile) {
+	const check = await validateDump(localFile);
+	if (!check.ok) {
+		discardPartialDump(globalsFileForDump(localFile));
+		discardPartialDump(localFile);
+		throw new BackupToolError(`The backup failed validation and was discarded: ${check.reason}`, "The dump was corrupt or truncated, so nothing was kept. Investigate before relying on this destination.");
+	}
+}
+/**
+* Say why a backup command failed, with no password in it.
+*
+* What reaches here is often a client tool's failure, and execa's message
+* repeats the tool's command line. The tools get the password through
+* `PGPASSWORD` now, so it is not on that line, but a connection string can
+* still arrive inside a message from elsewhere; this is the last place to
+* stop it reaching a terminal or a CI log.
+*/
+function reportError(err) {
+	if (err instanceof BackupToolError) {
+		outError(chalk.red(`  ✗ ${redactConnectionPasswords(err.message)}`));
+		if (err.hint) outError(chalk.gray(`    ${redactConnectionPasswords(err.hint)}`));
+	} else outError(chalk.red(`  ✗ ${redactConnectionPasswords(err instanceof Error ? err.message : String(err))}`));
+}
+function printBackupHelp() {
+	out(`
+${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). Never rebase: a backup
+                             without it cannot be restored
+  ${chalk.blue("--no-owner")}              Omit ownership commands from the dump
+  ${chalk.blue("--enable-row-security")}   Dump as an admin subject instead of failing on RLS
+                             ${chalk.red("(may produce a partial dump — see below)")}
+  ${chalk.blue("--row-security-role")} <r> Role to read as with the flag above (default: admin)
+
+${chalk.green.bold("Row-level security")}
+  On a managed Postgres the dumping role usually owns nothing and has no
+  BYPASSRLS, so pg_dump refuses:
+
+    ERROR: query would be affected by row-level security policy for table "..."
+
+  That refusal is the safe behaviour. --enable-row-security replaces it by
+  reading as an admin subject: Rebase sets app.uid/app.user_roles so the
+  generated admin_full_access policy admits the dump. The dump then contains
+  exactly what those policies admit ${chalk.red("and no error is raised for what they do not")} —
+  a table whose policies lack an admin rule comes out short, silently.
+
+  Granting the dumping role BYPASSRLS is the option that keeps a backup
+  meaning "every row".
+
+${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() {
+	out(`
+${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")}                 Replace what the backup holds, in one transaction with
+                             the restore (runs the dump through psql)
+  ${chalk.blue("--no-owner")}              Ignore ownership from the dump
+  ${chalk.blue("--continue-on-error")}     Log and continue past errors ${chalk.red("(may leave RLS un-enforced!)")}
+  ${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
+  asks for a typed 'yes' on a terminal, and with no terminal to ask on it
+  refuses. Prefer --create-db/--target-db to restore into a fresh database
+  rather than overwriting a live one. Into a database that already holds
+  what the backup creates, it needs --clean, and refuses before changing
+  anything without it. --clean drops each schema the backup creates whole,
+  with what it holds that the backup does not (it names those first), and
+  restores in the same transaction: a restore that stops changes nothing.
+
+  By default the restore aborts on the first error (--exit-on-error) so a
+  skipped GRANT never silently leaves RLS un-enforced. Roles are recreated
+  from the backup's .globals.sql sidecar first; keep that file next to the
+  dump. Use --continue-on-error only when you understand the consequences.
+`);
+}
+function printBackupsHelp() {
+	out(`
+${chalk.bold("rebase db backups")} — Manage stored backups
+
+${chalk.green.bold("Usage")}
+  rebase db backups list [--out <path|s3://bucket/prefix>]
+  rebase db backup list  [--out <path|s3://bucket/prefix>]   ${chalk.gray("(the same thing)")}
+`);
+}
+//#endregion
+export { buildBackupFilename as A, diagnoseRowSecurityDumpFailure as B, restoreDumpReplacing as C, resolvePgBinary as D, pgToolVariable as E, buildPgRestoreScriptArgs as F, parseDbNameFromUrl as G, joinStorageKey as H, buildPsqlScriptArgs as I, resolveConnectionString as J, parseDumpObjects as K, buildRowSecurityPgOptions as L, buildPgDumpallGlobalsArgs as M, buildPgRestoreArgs as N, selectBackupsToPrune as O, buildPgRestoreListArgs as P, checkToolServerCompatibility as R, restoreDump as S, validateDump as T, parseBackupDestination as U, globalsFileForDump as V, parseBackupTimestamp as W, splitGlobalsStatements as X, serverVersionNumToMajor as Y, withDatabaseName as Z, listBackups as _, BackupToolError as a, readDumpObjects as b, backup_service_exports as c, detectToolMajor as d, discardPartialDump as f, getServerVersionMajor as g, findRestoreConflicts as h, parseRestoreLine as i, buildPgDumpArgs as j, CLEAN_LOCK_TIMEOUT as k, createDump as l, findCleanExtras as m, parseBackupLine as n, CleanRestoreFailed as o, ensureDatabaseExists as p, parsePgToolMajor as q, parseBackupsListLine as r, applyGlobals as s, backup_cli_exports as t, describeUnreadableDump as u, preflight as v, uploadBackup as w, resetSharedSession as x, pruneBackups as y, cleanRestorePrelude as z };
 
-//# sourceMappingURL=backup-service-Bb39plam.js.map
+//# sourceMappingURL=backup-cli-PoRG-zEq.js.map