@rebasepro/server-postgres 0.25.0-canary.ge06257e → 0.25.1

package/dist/backup-cli-gijeXe0u.js

@@ -0,0 +1,1961 @@
+import { createRequire as __createRequire } from "module";
+__createRequire(import.meta.url);
+import { i as __exportAll, t as promptConfirm } from "./cli-prompt-DXG0yk-h.js";
+import { $ as forLibpq, et as redactConnectionPasswords, t as checkDatabaseConnectivity, tt as splitPassword, z as resolveLocalBin } from "./cli-errors-DiA0XFIS.js";
+import { a as outWarn, i as outError, r as out, t as chalk } from "./source-fZb92pN8.js";
+import { d as parseCommandFlags, l as closestWord, y as execa } from "./db-subcommands-BPoHCxJR.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.
+*
+* Everything in this file is side-effect free so it can be unit-tested
+* without a live Postgres server, matching the constraint that CI must
+* not require a database.
+*/
+/**
+* Extract the database name from a Postgres connection string.
+* Returns `null` when the URL has no database path (e.g. bare host).
+*/
+function parseDbNameFromUrl(connectionString) {
+	try {
+		const name = new URL(connectionString).pathname.replace(/^\//, "").trim();
+		return name.length > 0 ? name : null;
+	} catch {
+		const match = connectionString.match(/\/([^/?]+)(\?|$)/);
+		return match && match[1] ? match[1] : null;
+	}
+}
+/**
+* Swap the database name in a connection string, preserving credentials,
+* host, port and query params. Used by `--target-db` / `--create-db` so a
+* restore can target a fresh database instead of clobbering the live one.
+*/
+function withDatabaseName(connectionString, dbName) {
+	try {
+		const parsed = new URL(connectionString);
+		parsed.pathname = `/${dbName}`;
+		return parsed.toString();
+	} catch {
+		return connectionString.replace(/\/([^/?]+)(\?|$)/, `/${dbName}$2`);
+	}
+}
+/**
+* Parse the major version out of `pg_dump --version` / `pg_restore --version`
+* output, e.g. `"pg_dump (PostgreSQL) 16.2"` → `16`. Handles the pre-10
+* `9.6.x` scheme (returns `9`) and beta strings like `"17beta1"`.
+*/
+function parsePgToolMajor(versionOutput) {
+	const match = versionOutput.match(/(\d+)(?:\.(\d+))?/);
+	if (!match) return null;
+	const major = Number(match[1]);
+	if (!Number.isFinite(major)) return null;
+	if (major === 9 && match[2] !== void 0) return 9;
+	return major;
+}
+/**
+* Convert `SELECT current_setting('server_version_num')` (e.g. `160002`)
+* into a major version (`16`). Also accepts pre-10 encodings like `90603`
+* → `9`.
+*/
+function serverVersionNumToMajor(versionNum) {
+	const num = typeof versionNum === "string" ? Number(versionNum) : versionNum;
+	if (!Number.isFinite(num) || num <= 0) return null;
+	if (num < 1e5) return Math.floor(num / 1e4);
+	return Math.floor(num / 1e4);
+}
+/**
+* pg_dump / pg_restore must be **at least** as new as the server they talk
+* to. A newer client against an older server is supported; an older client
+* against a newer server is not and produces corrupt or rejected output.
+*/
+function checkToolServerCompatibility(toolMajor, serverMajor) {
+	if (toolMajor === null) return {
+		compatible: false,
+		reason: "Could not determine the client tool version."
+	};
+	if (serverMajor === null) return {
+		compatible: false,
+		reason: "Could not determine the Postgres server version."
+	};
+	if (toolMajor < serverMajor) return {
+		compatible: false,
+		reason: `Client tool is Postgres ${toolMajor} but the server is Postgres ${serverMajor}. pg_dump/pg_restore must be the same major version as the server or newer. Install Postgres ${serverMajor} client tools.`
+	};
+	return { compatible: true };
+}
+/**
+* Build a deterministic, sortable backup file name:
+*   `rebase-<db>-<YYYYMMDD>T<HHMMSS>Z.dump`
+*
+* The UTC timestamp is embedded so retention pruning can recover the
+* creation time from the object key alone, without extra metadata.
+*/
+function buildBackupFilename(dbName, date = /* @__PURE__ */ new Date()) {
+	const stamp = date.toISOString().replace(/\.\d+Z$/, "Z").replace(/[-:]/g, "");
+	return `rebase-${dbName.replace(/[^a-zA-Z0-9_-]/g, "_")}-${stamp}.dump`;
+}
+/**
+* Recover the creation timestamp encoded in a backup file name by
+* {@link buildBackupFilename}. Returns `null` for names that don't match,
+* so foreign objects in a shared prefix are never pruned.
+*/
+function parseBackupTimestamp(fileName) {
+	const match = (fileName.split("/").pop() ?? fileName).match(/-(\d{8})T(\d{6})Z\.dump$/);
+	if (!match) return null;
+	const [, ymd, hms] = match;
+	const iso = `${ymd.slice(0, 4)}-${ymd.slice(4, 6)}-${ymd.slice(6, 8)}T${hms.slice(0, 2)}:${hms.slice(2, 4)}:${hms.slice(4, 6)}Z`;
+	const date = new Date(iso);
+	return Number.isNaN(date.getTime()) ? null : date;
+}
+/**
+* Parse a destination string into a structured {@link BackupDestination}.
+* `s3://bucket/prefix` and `gs://bucket/prefix` map to object storage;
+* anything else is treated as a local path.
+*/
+function parseBackupDestination(out) {
+	const s3 = out.match(/^s3:\/\/([^/]+)\/?(.*)$/);
+	if (s3) return {
+		kind: "s3",
+		bucket: s3[1],
+		prefix: stripTrailingSlash(s3[2])
+	};
+	const gcs = out.match(/^gs:\/\/([^/]+)\/?(.*)$/);
+	if (gcs) return {
+		kind: "gcs",
+		bucket: gcs[1],
+		prefix: stripTrailingSlash(gcs[2])
+	};
+	return {
+		kind: "local",
+		path: out
+	};
+}
+function stripTrailingSlash(s) {
+	return s.replace(/\/+$/, "");
+}
+/**
+* Join a storage prefix and a file name without producing a leading or
+* doubled slash.
+*/
+function joinStorageKey(prefix, fileName) {
+	const clean = prefix.replace(/^\/+|\/+$/g, "");
+	return clean.length > 0 ? `${clean}/${fileName}` : fileName;
+}
+/**
+* `PGOPTIONS` carrying an identity, for a libpq tool that has no other way to
+* set a GUC.
+*
+* A backslash escape rather than quoting, which is what libpq's `-c` parsing
+* takes: a space inside a value ends the option otherwise, so a role list is
+* comma-joined and never spaced.
+*/
+function buildRowSecurityPgOptions(identity) {
+	const escape = (value) => value.replace(/([\\ ])/g, "\\$1");
+	return [
+		`-c app.uid=${escape(identity.uid)}`,
+		`-c app.user_id=${escape(identity.uid)}`,
+		`-c app.user_roles=${escape(identity.roles.join(","))}`
+	].join(" ");
+}
+/**
+* Assemble the `pg_dump` argument vector. Uses the custom format (`-Fc`),
+* which is compressed and restorable selectively via `pg_restore`.
+*/
+function buildPgDumpArgs(opts) {
+	const args = [
+		"--format=custom",
+		"--no-password",
+		`--file=${opts.outFile}`
+	];
+	if (opts.noOwner) args.push("--no-owner");
+	if (opts.rowSecurity) args.push("--enable-row-security");
+	for (const schema of opts.excludeSchemas ?? []) args.push(`--exclude-schema=${schema}`);
+	args.push(forLibpq(opts.connectionString));
+	return args;
+}
+/**
+* Whether a `pg_dump` failure is the row-security one, and what to do about it.
+*
+* The error text names the table and nothing else, so the first read of it is
+* "why would a backup be affected by RLS at all?" — the answer being that the
+* dumping role is not the tables' owner and has no `BYPASSRLS`, which is the
+* normal state of the `postgres` user on Cloud SQL, RDS and every other managed
+* Postgres. Nothing about that is visible from the message.
+*
+* Returns `null` for any other failure, so the caller reports it unchanged.
+*/
+function diagnoseRowSecurityDumpFailure(error) {
+	const text = [error?.stderr, error?.message].map((part) => typeof part === "string" ? part : "").join("\n");
+	if (!/row-level security policy/i.test(text)) return null;
+	const table = text.match(/for table "([^"]+)"/)?.[1];
+	return [
+		`pg_dump cannot read ${table ? `"${table}"` : "one of the tables"} because row-level security applies to it.`,
+		"",
+		"  The dumping role is neither the table's owner nor `BYPASSRLS`, which is the normal",
+		"  state of the `postgres` user on Cloud SQL, RDS and other managed Postgres — there is",
+		"  no superuser to hand out.",
+		"",
+		"  Two ways out:",
+		"",
+		"    • Grant the dumping role BYPASSRLS, or make it the owner, and run this again. The",
+		"      dump then contains every row, which is what a backup should mean.",
+		"",
+		"    • Re-run with --enable-row-security to dump as an admin subject instead. Rebase",
+		"      sets `app.uid`/`app.user_roles` so the generated `admin_full_access` policy",
+		"      admits the dump. Read the warning it prints: the result contains exactly the",
+		"      rows those policies admit, and any table whose policies do not include an",
+		"      admin rule comes out short — with no error.",
+		"",
+		"  Do not reach for a bare `pg_dump --enable-row-security` by hand. Without the",
+		"  settings above it succeeds and silently omits rows."
+	].join("\n");
+}
+/**
+* Assemble the `pg_restore` argument vector for a custom-format dump.
+*/
+function buildPgRestoreArgs(opts) {
+	const args = [
+		"--format=custom",
+		"--no-password",
+		`--dbname=${forLibpq(opts.connectionString)}`
+	];
+	if (opts.clean) args.push("--clean", "--if-exists");
+	if (opts.noOwner) args.push("--no-owner");
+	if (opts.exitOnError !== false) args.push("--exit-on-error");
+	args.push(opts.inputFile);
+	return args;
+}
+/**
+* Assemble the `pg_restore --list` argument vector. Reading a dump's table
+* of contents parses the whole archive without touching a database, so it is
+* a cheap integrity check that the file isn't truncated or corrupt.
+*/
+function buildPgRestoreListArgs(inputFile) {
+	return ["--list", inputFile];
+}
+/** `<id>; <catalog oid> <oid> <description> <namespace> <tag…> <owner>`, the shape of a TOC entry. */
+var TOC_ENTRY = /^\d+;\s+\d+\s+\d+\s+(SCHEMA|TABLE)\s+(?!DATA\s)(\S+)\s+(.+)\s+(\S+)$/;
+/** A TOC entry for a relation of any kind. `TABLE DATA`, `SEQUENCE SET` and `SEQUENCE OWNED BY` are not relations. */
+var TOC_RELATION = /^\d+;\s+\d+\s+\d+\s+(?:FOREIGN TABLE|MATERIALIZED VIEW|TABLE|VIEW|SEQUENCE)\s+(?!DATA\s|SET\s|OWNED BY\s)(\S+)\s+(.+)\s+(\S+)$/;
+/** A function's TOC entry: its tag is the name and the argument types, `two(integer, text)`. */
+var TOC_ROUTINE = /^\d+;\s+\d+\s+\d+\s+(?:FUNCTION|PROCEDURE|AGGREGATE)\s+(\S+)\s+(.+?)\(.*\)\s+\S+$/;
+/** A type's or a domain's TOC entry. */
+var TOC_TYPE = /^\d+;\s+\d+\s+\d+\s+(?:TYPE|DOMAIN)\s+(\S+)\s+(.+)\s+(\S+)$/;
+/**
+* The schemas and tables in `pg_restore --list` output: the objects a
+* restore without `--clean` fails on when the target already has them.
+*
+* A TOC line ends in the object's owner, after its namespace and its name;
+* a schema's namespace is `-`. The name is what lies between the two, so a
+* name with a space in it (`Odd Name`) reads whole. `TABLE DATA` and every
+* other kind of entry are not objects of their own here. Its relations,
+* functions and types are read too, for what `restore --clean` would drop
+* that the dump does not hold (`findCleanExtras`).
+*/
+function parseDumpObjects(list) {
+	const objects = {
+		schemas: [],
+		tables: [],
+		relations: [],
+		routines: [],
+		types: []
+	};
+	for (const line of list.split("\n")) {
+		const trimmed = line.trim();
+		const relation = TOC_RELATION.exec(trimmed);
+		if (relation) objects.relations.push({
+			schema: relation[1],
+			name: relation[2]
+		});
+		const routine = TOC_ROUTINE.exec(trimmed);
+		if (routine) objects.routines.push({
+			schema: routine[1],
+			name: routine[2]
+		});
+		const type = TOC_TYPE.exec(trimmed);
+		if (type) objects.types.push({
+			schema: type[1],
+			name: type[2]
+		});
+		const entry = TOC_ENTRY.exec(trimmed);
+		if (!entry) continue;
+		const [, kind, namespace, name] = entry;
+		if (kind === "SCHEMA") objects.schemas.push(name);
+		else objects.tables.push({
+			schema: namespace,
+			table: name
+		});
+	}
+	return objects;
+}
+/** A Postgres identifier, double-quoted. */
+function quoteIdentifier(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+/**
+* How long `restore --clean` waits for a lock before it gives up.
+*
+* A `rebase dev` serving from the database holds connections, and one inside a
+* transaction would otherwise make the restore wait without a word. The dump's
+* own script sets `lock_timeout = 0` after this, for the objects it creates.
+*/
+var CLEAN_LOCK_TIMEOUT = "15s";
+/**
+* What `restore --clean` runs first, in the transaction the restore runs in:
+* every schema the dump creates, dropped with `CASCADE`, and every table it
+* creates in a schema it does not (`public`), the same.
+*
+* `CASCADE`, which `pg_restore --clean` never uses: a table the backup lacks
+* in one of its schemas — `rebase.atlas_schema_revisions` from `rebase db
+* migrate`, a table a newer runtime added — is exactly what stopped its plain
+* `DROP SCHEMA rebase`, and a table that references one of the backup's is what
+* stops a plain `DROP TABLE`. The dump's script follows, with its own `DROP …
+* IF EXISTS` for everything else it creates.
+*/
+function cleanRestorePrelude(objects) {
+	const schemas = objects.schemas.filter((schema) => schema !== "public");
+	const dropped = new Set(schemas);
+	const tables = objects.tables.filter((table) => !dropped.has(table.schema));
+	return [
+		"SET client_min_messages = warning",
+		`SET lock_timeout = '15s'`,
+		...schemas.map((schema) => `DROP SCHEMA IF EXISTS ${quoteIdentifier(schema)} CASCADE`),
+		...tables.map((table) => `DROP TABLE IF EXISTS ${quoteIdentifier(table.schema)}.${quoteIdentifier(table.table)} CASCADE`)
+	];
+}
+/**
+* `pg_restore` writing the dump as a SQL script on stdout, with the `DROP …
+* IF EXISTS` that `--clean` adds, for `psql` to run. See {@link buildPsqlScriptArgs}.
+*/
+function buildPgRestoreScriptArgs(opts) {
+	return [
+		"--format=custom",
+		"--clean",
+		"--if-exists",
+		...opts.noOwner ? ["--no-owner"] : [],
+		"--file=-",
+		opts.inputFile
+	];
+}
+/**
+* `psql` running a script read from stdin, stopping at its first error.
+*
+* `-X`, so no `.psqlrc` changes what runs; `-q`, so it prints errors and
+* warnings, not a command tag per statement. The transaction is the script's
+* own: `restore --clean` writes the `BEGIN`, and the `COMMIT` only once
+* `pg_restore` has written the whole dump.
+*/
+function buildPsqlScriptArgs(connectionString) {
+	return [
+		"-X",
+		"-q",
+		"--no-password",
+		"-v",
+		"ON_ERROR_STOP=1",
+		`--dbname=${forLibpq(connectionString)}`,
+		"--file=-"
+	];
+}
+/**
+* Assemble the `pg_dumpall --globals-only` argument vector. Roles (and other
+* cluster-wide objects) live outside any single database, so a per-database
+* `pg_dump` omits them. Without the `rebase_user` role the RLS GRANT
+* statements in the main dump fail on restore and RLS is silently lost — so
+* every backup captures the globals into a sidecar `.globals.sql`.
+*
+* `--no-role-passwords` keeps role secrets out of the artifact (backups may
+* be shipped off-box); roles are recreated password-less and re-secured by
+* the operator.
+*/
+function buildPgDumpallGlobalsArgs(opts) {
+	return [
+		"--globals-only",
+		"--no-role-passwords",
+		"--no-password",
+		`--file=${opts.outFile}`,
+		`--dbname=${forLibpq(opts.connectionString)}`
+	];
+}
+/**
+* Derive the globals sidecar path/key for a given `.dump` file. Keeps the
+* two artifacts adjacent so listing, uploading and pruning can find one from
+* the other. A name that doesn't end in `.dump` is returned unchanged with a
+* `.globals.sql` suffix appended.
+*/
+function globalsFileForDump(dumpPath) {
+	return dumpPath.endsWith(".dump") ? dumpPath.slice(0, -5) + ".globals.sql" : dumpPath + ".globals.sql";
+}
+/**
+* Split a `pg_dumpall --globals-only` script into individual statements.
+* Used when replaying globals on restore so each `CREATE ROLE` / `GRANT`
+* can run independently and a benign "role already exists" on one doesn't
+* abort the rest. Drops `--` comment lines and blank statements.
+*/
+function splitGlobalsStatements(sql) {
+	return sql.split("\n").filter((line) => {
+		const trimmed = line.trim();
+		return !trimmed.startsWith("--") && !trimmed.startsWith("\\");
+	}).join("\n").split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+/**
+* Resolve the Postgres connection string the backup commands should use,
+* mirroring the precedence the branch command already relies on.
+*/
+function resolveConnectionString(env) {
+	return env.DATABASE_URL || env.ADMIN_CONNECTION_STRING || null;
+}
+//#endregion
+//#region src/backup/retention.ts
+/**
+* Retention pruning for scheduled backups. Pure logic — no I/O — so it can
+* be exhaustively unit-tested without touching a storage backend.
+*/
+/**
+* Decide which backups to delete under the given retention policy.
+*
+* Rules, applied in order:
+*  1. Objects whose key isn't a recognised rebase backup (no parseable
+*     timestamp and no `createdAt`) are never selected — foreign files in a
+*     shared bucket are left untouched.
+*  2. The `keepMinimum` newest backups are always retained.
+*  3. Of the remainder, any older than `retentionDays` are selected for
+*     deletion.
+*
+* Returns the keys to delete, oldest first.
+*/
+function selectBackupsToPrune(backups, options) {
+	const retentionDays = options.retentionDays ?? 0;
+	const keepMinimum = Math.max(0, options.keepMinimum ?? 0);
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	if (retentionDays <= 0) return [];
+	const dated = backups.map((b) => {
+		const createdAt = b.createdAt ?? parseBackupTimestamp(b.key);
+		return createdAt ? {
+			key: b.key,
+			createdAt
+		} : null;
+	}).filter((b) => b !== null);
+	dated.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+	const cutoff = now.getTime() - retentionDays * 24 * 60 * 60 * 1e3;
+	const toDelete = dated.slice(keepMinimum).filter((b) => b.createdAt.getTime() < cutoff);
+	toDelete.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+	return toDelete.map((b) => b.key);
+}
+//#endregion
+//#region src/backup/pg-binary.ts
+/**
+* Where the PostgreSQL client tools are, without spawning them.
+*
+* Kept apart from `backup-service.ts`, which pulls in `execa` (ESM-only), so
+* `createBackupCron` can check for the tools when it is registered.
+*/
+var OVERRIDE_VARIABLE = {
+	pg_dump: "PG_DUMP_PATH",
+	pg_restore: "PG_RESTORE_PATH",
+	pg_dumpall: "PG_DUMPALL_PATH",
+	psql: "PSQL_PATH"
+};
+/** The variable that points at `tool` when it is not on the PATH. */
+function pgToolVariable(tool) {
+	return OVERRIDE_VARIABLE[tool];
+}
+/** Locate `pg_dump` / `pg_restore` / `pg_dumpall` / `psql`, honouring an env override. */
+function resolvePgBinary(tool, env = process.env) {
+	const override = env[OVERRIDE_VARIABLE[tool]];
+	if (override && fs.existsSync(override)) return override;
+	return resolveLocalBin(tool);
+}
+//#endregion
+//#region src/backup/backup-logic.ts
+/**
+* Pure-ish orchestration for the backup/restore paths, kept free of `execa`
+* and `pg` value imports so it can be unit-tested under jest (the impure
+* edges — spawning processes, opening connections — live in
+* `backup-service.ts`, which is vitest/runtime only).
+*
+* The functions here take their side-effecting dependency as an argument
+* (a statement runner, an object deleter) so tests can inject fakes.
+*/
+/**
+* Replay a `pg_dumpall --globals-only` script one statement at a time,
+* tolerating per-statement failures. On a same-cluster restore the roles
+* usually already exist (`CREATE ROLE` → "already exists") and on a managed
+* provider an `ALTER ROLE <superuser>` may be refused; neither should abort
+* recreation of the roles that *are* missing. Returns how many statements
+* applied vs were skipped.
+*
+* `runStatement` executes one SQL statement and rejects on error.
+*/
+async function applyGlobalsWith(runStatement, globalsSql, log = () => {}) {
+	let applied = 0;
+	let skipped = 0;
+	for (const statement of splitGlobalsStatements(globalsSql)) try {
+		await runStatement(statement);
+		applied++;
+	} catch (err) {
+		skipped++;
+		log(`  • Skipped global: ${statement.split("\n")[0].slice(0, 80)} (${err instanceof Error ? err.message : String(err)})`);
+	}
+	return {
+		applied,
+		skipped
+	};
+}
+/**
+* Delete each pruned dump together with its `.globals.sql` roles sidecar, so
+* pruning never orphans the roles file. The sidecar is best-effort — older
+* backups predate it, so a missing-sidecar failure is swallowed while a
+* failure deleting the dump itself propagates.
+*
+* `deleteObject` removes one key and rejects if it cannot (e.g. not found).
+*/
+async function pruneWith(keys, deleteObject) {
+	for (const key of keys) {
+		await deleteObject(key);
+		try {
+			await deleteObject(globalsFileForDump(key));
+		} catch {}
+	}
+}
+/**
+* Remove a dump artifact abandoned by a failed tool run.
+*
+* `pg_dump` creates its `--file=` target before it finishes connecting, so any
+* failure — a URL libpq rejects, a dropped connection, a full disk — leaves a
+* 0-byte file behind. That corpse is not inert: `rebase db backups list` used
+* to show it as an ordinary entry, and `selectBackupsToPrune` ranks by
+* timestamp alone, so it occupies a protected `keepMinimum` slot and can push
+* a real backup out of retention.
+*
+* Best-effort on purpose: the caller is already throwing, and a failed unlink
+* must not replace the real diagnosis with an ENOENT/EPERM from the cleanup.
+*
+* Lives here rather than in `backup-service.ts` for the reason at the top of
+* this file — that module's top-level `execa` import makes it unloadable under
+* jest, so anything placed there cannot be unit-tested.
+*
+* `remove` deletes one file and throws if it cannot; `exists` reports presence.
+*/
+function discardPartialDumpWith(exists, remove, file) {
+	try {
+		if (exists(file)) remove(file);
+	} catch {}
+}
+//#endregion
+//#region src/backup/backup-service.ts
+/**
+* Backup / restore orchestration: thin, well-typed wrappers around
+* `pg_dump` and `pg_restore`, plus binary detection, version pre-flight,
+* and upload/prune against a storage backend.
+*
+* The pure argument- and policy-logic lives in `pg-tools.ts` and
+* `retention.ts`; this module is the impure edge (spawns processes, talks
+* to Postgres and storage) and is intentionally kept small.
+*/
+var backup_service_exports = /* @__PURE__ */ __exportAll({
+	BackupToolError: () => BackupToolError,
+	CleanRestoreFailed: () => CleanRestoreFailed,
+	applyGlobals: () => applyGlobals,
+	createDump: () => createDump,
+	describeUnreadableDump: () => describeUnreadableDump,
+	detectToolMajor: () => detectToolMajor,
+	discardPartialDump: () => discardPartialDump,
+	ensureDatabaseExists: () => ensureDatabaseExists,
+	findCleanExtras: () => findCleanExtras,
+	findRestoreConflicts: () => findRestoreConflicts,
+	getServerVersionMajor: () => getServerVersionMajor,
+	listBackups: () => listBackups,
+	preflight: () => preflight,
+	pruneBackups: () => pruneBackups,
+	readDumpObjects: () => readDumpObjects,
+	resetSharedSession: () => resetSharedSession,
+	resolvePgBinary: () => resolvePgBinary,
+	restoreDump: () => restoreDump,
+	restoreDumpReplacing: () => restoreDumpReplacing,
+	uploadBackup: () => uploadBackup,
+	validateDump: () => validateDump
+});
+/**
+* How a libpq tool is invoked for a connection string: the URL its command
+* line carries, and the environment it runs in.
+*
+* The password goes in `PGPASSWORD`, never on the command line, where every
+* process listing could read it and every failure printed it back (execa's
+* error repeats the command). See {@link splitPassword}.
+*/
+function libpqInvocation(connectionString, env) {
+	const split = splitPassword(connectionString);
+	const toolEnv = {};
+	for (const [key, value] of Object.entries(env)) if (value !== void 0) toolEnv[key] = value;
+	if (split.password !== null) toolEnv.PGPASSWORD = split.password;
+	return {
+		connectionString: split.connectionString,
+		env: toolEnv
+	};
+}
+/**
+* Remove a dump artifact abandoned by a failed tool run. See
+* {@link discardPartialDumpWith} for why this exists and why the logic lives
+* in the execa-free module.
+*/
+function discardPartialDump(file) {
+	discardPartialDumpWith((f) => fs.existsSync(f), (f) => fs.unlinkSync(f), file);
+}
+var BackupToolError = class extends Error {
+	hint;
+	constructor(message, hint) {
+		super(message);
+		this.hint = hint;
+		this.name = "BackupToolError";
+	}
+};
+/** Run `<bin> --version` and extract the major version. */
+async function detectToolMajor(bin) {
+	try {
+		const { stdout } = await execa(bin, ["--version"]);
+		return parsePgToolMajor(stdout);
+	} catch {
+		return null;
+	}
+}
+/** Query the server for its major version via `server_version_num`. */
+async function getServerVersionMajor(connectionString) {
+	const { Client } = await import("pg");
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		const raw = (await client.query("SHOW server_version_num")).rows?.[0]?.server_version_num;
+		return serverVersionNumToMajor(raw);
+	} finally {
+		await client.end();
+	}
+}
+/** PGlite names itself in `version()`: `PostgreSQL 18.3 (PGlite 0.5.6) on wasm32-…`. */
+var SHARED_SESSION_ENGINE = /\(PGlite\b/i;
+/**
+* Put back what a client tool left set on a database that is one session
+* every connection shares, and do nothing on any other.
+*
+* The managed development database is PGlite: one session behind a socket
+* server, so what `pg_dump` sets for itself — `search_path` emptied,
+* `row_security` off, `PREPARE dumpEnumType …` — stays set for every client
+* after it, a running `rebase dev` included. One `rebase db backup` there left
+* every API request answering 500 "table does not exist", a restart did not
+* help (the database outlives `rebase dev`), and the next backup failed on
+* `prepared statement "dumpenumtype" already exists`.
+*
+* `RESET ALL` and `DEALLOCATE ALL`, not `DISCARD ALL`: that would also drop
+* the `LISTEN` a running `rebase dev`'s realtime holds on the same session.
+* Best effort: it runs after the tool, whose own outcome is what the caller
+* reports.
+*/
+async function resetSharedSession(connectionString) {
+	const { Client } = await import("pg");
+	const client = new Client({
+		connectionString,
+		connectionTimeoutMillis: 1e4,
+		query_timeout: 15e3
+	});
+	client.on("error", () => void 0);
+	try {
+		await client.connect();
+		const { rows } = await client.query("SELECT version() AS version");
+		if (!SHARED_SESSION_ENGINE.test(rows[0]?.version ?? "")) return;
+		await client.query("RESET ALL");
+		await client.query("DEALLOCATE ALL");
+	} catch {} finally {
+		await client.end().catch(() => void 0);
+	}
+}
+/**
+* Verify the requested client tool exists and its major version is
+* compatible with the live server. Throws {@link BackupToolError} — with a
+* doctor-style hint — when the binary is missing.
+*/
+async function preflight(tool, connectionString, env = process.env) {
+	const bin = resolvePgBinary(tool, env);
+	if (!bin) throw new BackupToolError(`Could not find the '${tool}' binary.`, `Install the PostgreSQL client tools (e.g. 'brew install libpq' or 'apt-get install postgresql-client'), or set ${tool === "pg_dump" ? "PG_DUMP_PATH" : "PG_RESTORE_PATH"} to its full path.`);
+	const [toolMajor, serverMajor] = await Promise.all([detectToolMajor(bin), getServerVersionMajor(connectionString)]);
+	return {
+		bin,
+		toolMajor,
+		serverMajor,
+		...checkToolServerCompatibility(toolMajor, serverMajor)
+	};
+}
+/**
+* Produce a custom-format dump on local disk. When `outDir` is omitted the
+* file is written to the OS temp directory (used by the upload path, which
+* cleans it up afterwards).
+*
+* Alongside the `-Fc` dump it writes a `<name>.globals.sql` sidecar via
+* `pg_dumpall --globals-only` so the roles the dump's GRANT/RLS statements
+* depend on can be recreated on restore. Set `includeGlobals: false` to skip
+* it (e.g. when the caller has no privilege to read cluster globals).
+*/
+async function createDump(opts) {
+	const env = opts.env ?? process.env;
+	const bin = resolvePgBinary("pg_dump", env);
+	if (!bin) throw new BackupToolError("Could not find the 'pg_dump' binary.", "Install the PostgreSQL client tools or set PG_DUMP_PATH.");
+	const fileName = opts.fileName ?? buildBackupFilename(opts.dbName);
+	const outDir = opts.outDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "rebase-backup-"));
+	fs.mkdirSync(outDir, { recursive: true });
+	const localFile = path.join(outDir, fileName);
+	createOwnerOnly(localFile);
+	const tool = libpqInvocation(opts.connectionString, env);
+	const args = buildPgDumpArgs({
+		connectionString: tool.connectionString,
+		outFile: localFile,
+		excludeSchemas: opts.excludeSchemas,
+		noOwner: opts.noOwner,
+		rowSecurity: opts.rowSecurity
+	});
+	const dumpEnv = { ...tool.env };
+	if (opts.rowSecurity) dumpEnv.PGOPTIONS = [env.PGOPTIONS, buildRowSecurityPgOptions(opts.rowSecurity)].filter(Boolean).join(" ");
+	try {
+		try {
+			await execa(bin, args, {
+				stdio: opts.inheritStdio ? "inherit" : "pipe",
+				env: dumpEnv
+			});
+		} finally {
+			await resetSharedSession(opts.connectionString);
+		}
+	} catch (error) {
+		discardPartialDump(localFile);
+		const diagnosis = diagnoseRowSecurityDumpFailure(error);
+		if (!diagnosis) throw error;
+		throw new BackupToolError(diagnosis, "Run `rebase db backup --help` for the flag, and read what it says about partial dumps.");
+	}
+	const result = {
+		localFile,
+		fileName,
+		sizeBytes: fs.existsSync(localFile) ? fs.statSync(localFile).size : 0
+	};
+	if (opts.includeGlobals !== false) {
+		const dumpallBin = resolvePgBinary("pg_dumpall", env);
+		if (!dumpallBin) throw new BackupToolError("Could not find the 'pg_dumpall' binary needed to capture cluster roles.", "Install the PostgreSQL client tools or set PG_DUMPALL_PATH. To take a role-incomplete backup anyway, pass includeGlobals: false.");
+		const globalsFile = globalsFileForDump(localFile);
+		createOwnerOnly(globalsFile);
+		try {
+			try {
+				await execa(dumpallBin, buildPgDumpallGlobalsArgs({
+					connectionString: tool.connectionString,
+					outFile: globalsFile
+				}), {
+					stdio: opts.inheritStdio ? "inherit" : "pipe",
+					env: tool.env
+				});
+			} finally {
+				await resetSharedSession(opts.connectionString);
+			}
+		} catch (error) {
+			discardPartialDump(globalsFile);
+			discardPartialDump(localFile);
+			throw error;
+		}
+		result.globalsFile = globalsFile;
+		result.globalsSizeBytes = fs.existsSync(globalsFile) ? fs.statSync(globalsFile).size : 0;
+	}
+	return result;
+}
+/**
+* Create `file` empty and readable by its owner only, before a tool writes it.
+*
+* A dump holds every row, and the `.globals.sql` sidecar every role's password
+* hash. pg_dump and pg_dumpall create their `--file=` target with the
+* process's umask — 0644 on most machines, readable by every user — and keep
+* the mode of a file that is already there. Created 0600 first, the file is
+* never readable by anyone else, not even while the dump runs; chmod-ing it
+* afterwards would leave it open for as long as that takes. A file that
+* already existed is narrowed too.
+*/
+function createOwnerOnly(file) {
+	fs.closeSync(fs.openSync(file, "w", 384));
+	fs.chmodSync(file, 384);
+}
+/**
+* Cheap integrity check on a freshly written dump: it must be non-empty and
+* `pg_restore --list` must parse its table of contents without error. Used
+* before pruning older backups so a corrupt-but-exit-0 dump never becomes
+* the reason the last good backup is deleted.
+*/
+async function validateDump(localFile, env = process.env) {
+	if (!fs.existsSync(localFile)) return {
+		ok: false,
+		reason: `Dump file does not exist: ${localFile}`
+	};
+	if (fs.statSync(localFile).size === 0) return {
+		ok: false,
+		reason: "Dump file is empty (0 bytes)."
+	};
+	const bin = resolvePgBinary("pg_restore", env);
+	if (!bin) return {
+		ok: false,
+		reason: "Could not find 'pg_restore' to verify the dump."
+	};
+	try {
+		await execa(bin, buildPgRestoreListArgs(localFile), {
+			stdio: "pipe",
+			env: { ...env }
+		});
+		return { ok: true };
+	} catch (err) {
+		return {
+			ok: false,
+			reason: `pg_restore --list failed: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+}
+/**
+* Replay a `pg_dumpall --globals-only` script to recreate cluster roles
+* before a restore, so the dump's GRANT/RLS statements (which reference
+* `rebase_user` and any owner roles) actually apply. Runs statement by
+* statement and tolerates per-statement failures — on a same-cluster restore
+* the roles usually already exist (`CREATE ROLE` → "already exists"), and on
+* a managed provider an `ALTER ROLE <superuser>` may be refused; neither
+* should abort role recreation. Returns how many statements applied vs were
+* skipped.
+*/
+async function applyGlobals(connectionString, globalsSql, log = () => {}) {
+	const { Client } = await import("pg");
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		return await applyGlobalsWith(async (sql) => {
+			await client.query(sql);
+		}, globalsSql, log);
+	} finally {
+		await client.end();
+	}
+}
+/**
+* Restore a custom-format dump into the database named by
+* `connectionString`. Destructive when `clean` is set (drops objects
+* first). Never called automatically — the CLI gates it behind explicit
+* confirmation.
+*
+* Runs with `--exit-on-error` by default: a restore that logs-and-continues
+* past a failed GRANT (because a role was missing) reports success with RLS
+* un-enforced. Callers should recreate roles first (see {@link applyGlobals})
+* and only set `exitOnError: false` deliberately.
+*/
+async function restoreDump(opts) {
+	const env = opts.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 tool = libpqInvocation(opts.connectionString, env);
+	const args = buildPgRestoreArgs({
+		connectionString: tool.connectionString,
+		inputFile: opts.inputFile,
+		clean: opts.clean,
+		noOwner: opts.noOwner,
+		exitOnError: opts.exitOnError
+	});
+	try {
+		await execa(bin, args, {
+			stdio: opts.inheritStdio ? "inherit" : "pipe",
+			env: tool.env
+		});
+	} finally {
+		await resetSharedSession(opts.connectionString);
+	}
+}
+/**
+* A `restore --clean` that stopped, and so was rolled back whole.
+*
+* `tool` is the one that stopped it: `pg_restore`, writing the dump's script,
+* or `psql`, running it. `lockTimeout` when what `psql` stopped on was the
+* wait for a lock — `CLEAN_LOCK_TIMEOUT` in `pg-tools.ts`.
+*/
+var CleanRestoreFailed = class extends Error {
+	tool;
+	exitCode;
+	lockTimeout;
+	constructor(tool, exitCode, lockTimeout) {
+		super(`${tool} exited with code ${exitCode ?? "unknown"}`);
+		this.tool = tool;
+		this.exitCode = exitCode;
+		this.lockTimeout = lockTimeout;
+		this.name = "CleanRestoreFailed";
+	}
+};
+/**
+* Restore a dump over what the database holds, as one transaction:
+* {@link cleanRestorePrelude} first, then the dump as `pg_restore` writes it
+* for `psql`, and the `COMMIT` only after the last of it.
+*
+* One unit, so it either replaces what the dump holds or changes nothing:
+* `pg_restore --clean` runs each statement on its own, so the drops it starts
+* with had all happened when a later one failed — and its plain `DROP SCHEMA
+* rebase` fails on any table the backup lacks, which left a database with
+* every table dropped and nothing restored. Here a failure anywhere —
+* `pg_restore` cannot read the archive, a statement fails, the connection
+* drops — ends the transaction without a `COMMIT`, and Postgres rolls it back.
+*
+* Throws {@link CleanRestoreFailed} when it did not commit.
+*/
+async function restoreDumpReplacing(opts) {
+	const env = opts.env ?? process.env;
+	const restoreBin = resolvePgBinary("pg_restore", env);
+	const psqlBin = resolvePgBinary("psql", env);
+	if (!restoreBin || !psqlBin) {
+		const tool = restoreBin ? "psql" : "pg_restore";
+		throw new BackupToolError(`Could not find the '${tool}' binary${tool === "psql" ? ", which runs a --clean restore as one transaction" : ""}.`, `Install the PostgreSQL client tools or set ${pgToolVariable(tool)}.`);
+	}
+	const tool = libpqInvocation(opts.connectionString, env);
+	const script = execa(restoreBin, buildPgRestoreScriptArgs({
+		inputFile: opts.inputFile,
+		noOwner: opts.noOwner
+	}), {
+		stdin: "ignore",
+		stdout: "pipe",
+		stderr: opts.inheritStdio ? "inherit" : "ignore",
+		buffer: false,
+		reject: false,
+		env: tool.env
+	});
+	const apply = execa(psqlBin, buildPsqlScriptArgs(tool.connectionString), {
+		stdin: "pipe",
+		stdout: "ignore",
+		stderr: opts.inheritStdio ? ["pipe", "inherit"] : "pipe",
+		reject: false,
+		env: tool.env
+	});
+	const sink = apply.stdin;
+	const source = script.stdout;
+	if (!sink || !source) throw new BackupToolError("Could not connect pg_restore to psql.");
+	sink.on("error", () => void 0);
+	apply.once("exit", () => {
+		source.unpipe(sink);
+		source.resume();
+		script.kill();
+	});
+	sink.write(["BEGIN", ...cleanRestorePrelude(opts.objects)].map((statement) => `${statement};\n`).join(""));
+	source.pipe(sink, { end: false });
+	const written = await script;
+	const committed = written.exitCode === 0 && sink.writable;
+	sink.end(committed ? "COMMIT;\n" : void 0);
+	const applied = await apply;
+	await resetSharedSession(opts.connectionString);
+	if (applied.exitCode !== 0) {
+		const stderr = typeof applied.stderr === "string" ? applied.stderr : "";
+		throw new CleanRestoreFailed("psql", applied.exitCode, /lock timeout/i.test(stderr));
+	}
+	if (!committed) throw new CleanRestoreFailed("pg_restore", written.exitCode, false);
+}
+/**
+* What `restore --clean` drops that the backup does not hold, so it can say
+* so before it runs: what a schema the backup replaces whole holds that it has
+* no copy of — tables, views, sequences, functions, procedures, aggregates,
+* types and domains — and the views and foreign keys elsewhere that reference
+* one of the relations it replaces. As `<kind> <name>`.
+*
+* A function is matched by its name, so an overload the backup lacks beside
+* one it holds is not named. Sequences a column owns go with their table,
+* and what an extension owns with the extension, so neither is named.
+*
+* None for a database that does not exist yet.
+*/
+async function findCleanExtras(connectionString, objects) {
+	const schemas = objects.schemas.filter((schema) => schema !== "public");
+	if (schemas.length === 0 && objects.relations.length === 0) return [];
+	const { routines, types } = objects;
+	const { Client } = await import("pg");
+	const client = new Client({ connectionString });
+	try {
+		await client.connect();
+	} catch (err) {
+		if (err instanceof Error && "code" in err && err.code === "3D000") return [];
+		throw err;
+	}
+	try {
+		const { rows } = await client.query(`WITH dumped AS (
+                 SELECT c.oid
+                   FROM pg_class c
+                   JOIN pg_namespace n ON n.oid = c.relnamespace
+                   JOIN unnest($2::text[], $3::text[]) AS d(schema_name, rel_name)
+                     ON d.schema_name = n.nspname AND d.rel_name = c.relname
+             )
+             SELECT kind, name FROM (
+                 SELECT CASE c.relkind WHEN 'v' THEN 'view' WHEN 'm' THEN 'materialized view'
+                                       WHEN 'f' THEN 'foreign table' WHEN 'S' THEN 'sequence' ELSE 'table' END AS kind,
+                        n.nspname || '.' || c.relname AS name
+                   FROM pg_class c
+                   JOIN pg_namespace n ON n.oid = c.relnamespace
+                  WHERE n.nspname = ANY($1::text[])
+                    AND c.relkind IN ('r', 'p', 'v', 'm', 'f', 'S')
+                    AND c.oid NOT IN (SELECT oid FROM dumped)
+                    AND NOT (c.relkind = 'S' AND EXISTS (
+                        SELECT 1 FROM pg_depend owner
+                         WHERE owner.classid = 'pg_class'::regclass AND owner.objid = c.oid
+                           AND owner.deptype IN ('a', 'i')))
+                 UNION
+                 SELECT CASE p.prokind WHEN 'p' THEN 'procedure' WHEN 'a' THEN 'aggregate' ELSE 'function' END,
+                        n.nspname || '.' || p.proname
+                   FROM pg_proc p
+                   JOIN pg_namespace n ON n.oid = p.pronamespace
+                  WHERE n.nspname = ANY($1::text[])
+                    AND (n.nspname, p.proname) NOT IN (SELECT * FROM unnest($4::text[], $5::text[]))
+                    AND NOT EXISTS (
+                        SELECT 1 FROM pg_depend owner
+                         WHERE owner.classid = 'pg_proc'::regclass AND owner.objid = p.oid
+                           AND owner.deptype IN ('e', 'i'))
+                 UNION
+                 SELECT CASE t.typtype WHEN 'd' THEN 'domain' ELSE 'type' END,
+                        n.nspname || '.' || t.typname
+                   FROM pg_type t
+                   JOIN pg_namespace n ON n.oid = t.typnamespace
+                  WHERE n.nspname = ANY($1::text[])
+                    AND (t.typtype IN ('e', 'd', 'r')
+                         OR (t.typtype = 'c' AND EXISTS (
+                             SELECT 1 FROM pg_class tc WHERE tc.oid = t.typrelid AND tc.relkind = 'c')))
+                    AND (n.nspname, t.typname) NOT IN (SELECT * FROM unnest($6::text[], $7::text[]))
+                    AND NOT EXISTS (
+                        SELECT 1 FROM pg_depend owner
+                         WHERE owner.classid = 'pg_type'::regclass AND owner.objid = t.oid
+                           AND owner.deptype = 'e')
+                 UNION
+                 SELECT 'view', vn.nspname || '.' || v.relname
+                   FROM pg_depend dep
+                   JOIN pg_rewrite r ON r.oid = dep.objid AND dep.classid = 'pg_rewrite'::regclass
+                   JOIN pg_class v ON v.oid = r.ev_class
+                   JOIN pg_namespace vn ON vn.oid = v.relnamespace
+                  WHERE dep.refobjid IN (SELECT oid FROM dumped)
+                    AND v.oid NOT IN (SELECT oid FROM dumped)
+                    AND NOT vn.nspname = ANY($1::text[])
+                 UNION
+                 SELECT 'foreign key', con.conname || ' on ' || cn.nspname || '.' || cr.relname
+                   FROM pg_constraint con
+                   JOIN pg_class cr ON cr.oid = con.conrelid
+                   JOIN pg_namespace cn ON cn.oid = cr.relnamespace
+                  WHERE con.contype = 'f'
+                    AND con.confrelid IN (SELECT oid FROM dumped)
+                    AND con.conrelid NOT IN (SELECT oid FROM dumped)
+                    AND NOT cn.nspname = ANY($1::text[])
+             ) extra
+             ORDER BY name`, [
+			schemas,
+			objects.relations.map((r) => r.schema),
+			objects.relations.map((r) => r.name),
+			routines.map((r) => r.schema),
+			routines.map((r) => r.name),
+			types.map((t) => t.schema),
+			types.map((t) => t.name)
+		]);
+		return rows.map((row) => `${row.kind} ${row.name}`);
+	} finally {
+		await client.end();
+	}
+}
+/** The schemas and tables a dump creates, from `pg_restore --list`. See {@link parseDumpObjects}. */
+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));
+	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,
+* as `schema <name>` / `table <schema>.<name>`: what a restore without
+* `--clean` would stop on. `public` is left out of the schemas — every
+* database has it, and pg_restore does not create it. None for a database
+* that does not exist yet.
+*/
+async function findRestoreConflicts(connectionString, objects) {
+	const schemas = objects.schemas.filter((schema) => schema !== "public");
+	if (schemas.length === 0 && objects.tables.length === 0) return [];
+	const { Client } = await import("pg");
+	const client = new Client({ connectionString });
+	try {
+		await client.connect();
+	} catch (err) {
+		if (err instanceof Error && "code" in err && err.code === "3D000") return [];
+		throw err;
+	}
+	try {
+		const existingSchemas = await client.query("SELECT nspname FROM pg_namespace WHERE nspname = ANY($1::text[]) ORDER BY nspname", [schemas]);
+		const existingTables = await client.query(`SELECT n.nspname, c.relname
+               FROM pg_class c
+               JOIN pg_namespace n ON n.oid = c.relnamespace
+               JOIN unnest($1::text[], $2::text[]) AS d(schema_name, table_name)
+                 ON d.schema_name = n.nspname AND d.table_name = c.relname
+              WHERE c.relkind IN ('r', 'p')
+              ORDER BY n.nspname, c.relname`, [objects.tables.map((t) => t.schema), objects.tables.map((t) => t.table)]);
+		return [...existingSchemas.rows.map((row) => `schema ${row.nspname}`), ...existingTables.rows.map((row) => `table ${row.nspname}.${row.relname}`)];
+	} finally {
+		await client.end();
+	}
+}
+/**
+* Create a database (if absent) by connecting to the maintenance
+* `postgres` database. Used by `restore --create-db`.
+*/
+async function ensureDatabaseExists(adminConnectionString, dbName) {
+	const { Client } = await import("pg");
+	const parsed = new URL(adminConnectionString);
+	parsed.pathname = "/postgres";
+	const client = new Client({ connectionString: parsed.toString() });
+	await client.connect();
+	try {
+		const existing = await client.query("SELECT 1 FROM pg_database WHERE datname = $1", [dbName]);
+		if (existing.rowCount && existing.rowCount > 0) return false;
+		if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(dbName)) throw new BackupToolError(`Invalid database name: "${dbName}"`);
+		await client.query(`CREATE DATABASE "${dbName}"`);
+		return true;
+	} finally {
+		await client.end();
+	}
+}
+/**
+* Upload a local dump to object storage under the destination's prefix.
+* Backups may contain secrets/PII, so the object is written with a
+* private/octet-stream content type; bucket-level ACLs must stay private.
+*/
+async function uploadBackup(storage, localFile, dest) {
+	const fileName = path.basename(localFile);
+	const key = joinStorageKey(dest.prefix, fileName);
+	const file = new File([await fs.openAsBlob(localFile)], fileName, { type: "application/octet-stream" });
+	return {
+		key,
+		storageUrl: (await storage.putObject({
+			file,
+			key,
+			bucket: dest.bucket,
+			metadata: { "rebase-backup": "1" }
+		}, { uploadLimits: false })).storageUrl
+	};
+}
+/** Stats in flight at once while listing a local backup folder. */
+var LOCAL_STAT_CONCURRENCY = 32;
+/** `fn` over `items`, at most `limit` at a time; results in input order. */
+async function mapBounded(items, limit, fn) {
+	const results = new Array(items.length);
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const i = next++;
+			results[i] = await fn(items[i]);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+	return results;
+}
+/**
+* List existing backups at a destination. For local destinations reads the
+* directory; for object storage lists the prefix via the controller.
+*/
+async function listBackups(dest, storage) {
+	if (dest.kind === "local") {
+		const stat = await fs.promises.stat(dest.path).catch(() => null);
+		if (!stat) return [];
+		const dir = stat.isDirectory() ? dest.path : path.dirname(dest.path);
+		const dumps = (await fs.promises.readdir(dir)).filter((f) => f.endsWith(".dump"));
+		const stats = await mapBounded(dumps, LOCAL_STAT_CONCURRENCY, (f) => fs.promises.stat(path.join(dir, f)));
+		return dumps.map((f, i) => {
+			const createdAt = parseBackupTimestamp(f) ?? stats[i].mtime;
+			return {
+				key: path.join(dir, f),
+				createdAt,
+				sizeBytes: stats[i].size
+			};
+		}).sort((a, b) => (b.createdAt?.getTime() ?? 0) - (a.createdAt?.getTime() ?? 0));
+	}
+	if (!storage) throw new BackupToolError(`Listing ${dest.kind} backups requires a configured storage backend.`);
+	const { listBackupObjects } = await import("@rebasepro/server");
+	return (await listBackupObjects(dest, storage)).map((info) => ({
+		key: info.key,
+		createdAt: info.createdAt ? new Date(info.createdAt) : void 0
+	}));
+}
+/**
+* Apply a retention policy to a destination, deleting the backups selected
+* by {@link selectBackupsToPrune}. Returns the keys that were removed.
+*/
+async function pruneBackups(dest, options, storage) {
+	const toDelete = selectBackupsToPrune(await listBackups(dest, storage), options);
+	await pruneWith(toDelete, dest.kind === "local" ? async (key) => {
+		if (!fs.existsSync(key)) throw new Error(`not found: ${key}`);
+		fs.unlinkSync(key);
+	} : async (key) => {
+		if (!storage) throw new BackupToolError("Storage backend required to prune object backups.");
+		await storage.deleteObject(key, dest.bucket);
+	});
+	return toDelete;
+}
+//#endregion
+//#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-cli-gijeXe0u.js.map