@rebasepro/server-postgres 0.12.1-canary.gdfba2a1 → 0.12.1-canary.ge1bb178

package/src/PostgresBootstrapper.ts

@@ -102,6 +102,40 @@ export interface PostgresDriverInternals {
 
 // Re-export from shared CLI error utilities
 import { isEconnrefused } from "./cli-errors";
+import { classifyConnectFailure } from "./utils/pg-error-utils";
+
+/**
+ * Which table name the boot-time drift check should look for, for one collection.
+ *
+ * A declared `table` IS the table name, not a hint to be second-guessed. This
+ * used to ask the registry whether it had indexed the declared name and fall
+ * back to the SLUG when it had not — but "the registry does not know this table"
+ * is exactly the condition the drift check exists to report, so the fallback
+ * fired precisely when it was most harmful.
+ *
+ * A collection with `slug: "usage-daily", table: "usage_daily"` was reported as
+ * missing table `usage-daily`: a name that does not exist, should never exist,
+ * and that nobody can find by looking. Worse, the remediation the caller prints
+ * says to run `rebase db push` — which would then CREATE that invented table
+ * beside the correct one, the same "second copy" hazard the misplaced-schema
+ * branch further down exists to prevent. Seen in production, where a correctly
+ * migrated database reported drift on every boot.
+ *
+ * The slug is used only when nothing was declared, which is the config shape
+ * where the slug genuinely is the table name.
+ *
+ * Exported for its own test: the caller needs a live pool and a real database,
+ * and this is the part that was wrong.
+ */
+export function resolveDriftCheckName(
+    col: CollectionConfig,
+    registeredTableNames: string[]
+): string {
+    const declaredTable = isRelationalCollectionConfig(col) ? col.table : undefined;
+    return declaredTable
+        ?? registeredTableNames.find((k) => k === col.slug)
+        ?? col.slug;
+}
 
 /**
  * Default PostgreSQL bootstrapper.
@@ -260,9 +294,45 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                     throw new Error(`Cannot connect to PostgreSQL at ${hostInfo}: connection refused. Is the database running?`);
                 }
 
-                // For other errors (timeouts, auth failures, etc.) warn but continue —
-                // the pool may recover on subsequent attempts.
-                logger.error("❌ Failed to connect to PostgreSQL", { error: err });
+                /*
+                 * Everything else.
+                 *
+                 * Two problems with what used to happen here. First, the logged
+                 * error was Drizzle's wrapper — `Failed query: SELECT 1` and a
+                 * stack through drizzle internals — while the sentence that
+                 * actually says what is wrong ("password authentication failed
+                 * for user …", "database … does not exist") sits in `.cause`
+                 * and was never printed. A developer with a typo in their
+                 * DATABASE_URL got two walls of stack trace and no cause.
+                 *
+                 * Second, "continuing… the pool may recover" is only true for
+                 * a transient fault. A wrong password or a missing database is
+                 * settled: the next query fails the same way, so the process
+                 * died seconds later anyway — after printing a reassurance.
+                 * Those now fail here, where the message can be about the
+                 * cause rather than about whichever query ran next.
+                 */
+                const { fatal, reason, code } = classifyConnectFailure(err);
+                const detail = code ? ` [${code}]` : "";
+
+                if (fatal) {
+                    logger.error(
+                        `\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+                        `  ❌  PostgreSQL refused the connection\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+                        `\n` +
+                        `  ${reason}${detail}\n` +
+                        `\n` +
+                        `  The server is reachable, so this is the credentials or the\n` +
+                        `  database name in DATABASE_URL — check them in your .env.\n` +
+                        `\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`
+                    );
+                    throw new Error(`PostgreSQL refused the connection: ${reason}${detail}`);
+                }
+
+                logger.error(`❌ Failed to connect to PostgreSQL: ${reason}${detail}`, { error: err });
                 logger.warn("⚠️ Continuing without initial database verification. Drizzle/PG will attempt to connect on subsequent queries.");
             }
 
@@ -487,22 +557,28 @@ table: link.table });
             try {
                 const registeredCollections = registry.getCollections();
                 if (registeredCollections.length > 0) {
-                    const schemasToCheck = Array.from(new Set(
-                        registeredCollections.map(c => "schema" in c && c.schema ? c.schema : "public")
-                    ));
-                    const schemasList = schemasToCheck.map(s => `'${s}'`).join(",");
+                    // Deliberately unfiltered by schema: a table that is missing
+                    // from where the collection says it lives is very often
+                    // sitting in another schema entirely (see the misplaced-table
+                    // report below), and knowing *which* is the whole answer.
                     const result = await schemaAwareDb.execute(sql.raw(`
                         SELECT table_name, table_schema
                         FROM information_schema.tables
-                        WHERE table_schema IN (${schemasList})
+                        WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
                           AND table_type = 'BASE TABLE'
                     `));
+                    const tablesByName = new Map<string, string[]>();
+                    for (const row of result.rows as Array<{ table_name: string; table_schema: string }>) {
+                        const schemas = tablesByName.get(row.table_name) ?? [];
+                        schemas.push(row.table_schema);
+                        tablesByName.set(row.table_name, schemas);
+                    }
                     const dbTables = new Set(
                         (result.rows as Array<{ table_name: string; table_schema: string }>).map(r =>
                             r.table_schema === "public" ? r.table_name : `${r.table_schema}.${r.table_name}`
                         )
                     );
-                    const missing: Array<{ slug: string; table: string }> = [];
+                    const missing: Array<{ slug: string; table: string; foundIn: string[] }> = [];
                     for (const col of registeredCollections) {
                         // Auth owns its table and creates it later in this same
                         // boot (initializeAuth → ensureAuthTablesExist), so it is
@@ -513,41 +589,72 @@ table: link.table });
                         if ((col as { auth?: { enabled?: boolean } }).auth?.enabled) continue;
 
                         const schemaName = "schema" in col && col.schema ? col.schema : "public";
-                        const declaredTable = isRelationalCollectionConfig(col) ? col.table : undefined;
-                        const tableName = registry.hasTableForCollection(
-                            declaredTable ?? col.slug
-                        )
-                            ? (declaredTable ?? col.slug)
-                            : col.slug;
-                        // Resolve the actual table name the registry stored
-                        const resolvedTable = registry.getTableNames().find((k) =>
-                            k === tableName ||
-                            k === col.slug
-                        );
-                        const checkName = resolvedTable ?? tableName;
+                        const checkName = resolveDriftCheckName(col, registry.getTableNames());
                         const fullCheckName = schemaName === "public" ? checkName : `${schemaName}.${checkName}`;
                         if (!dbTables.has(fullCheckName)) {
                             // Report what was actually looked up: an unqualified
                             // "users" sends people hunting for public.users.
                             missing.push({ slug: col.slug,
-table: fullCheckName });
+table: fullCheckName,
+foundIn: (tablesByName.get(checkName) ?? []).filter(s => s !== schemaName) });
                         }
                     }
                     if (missing.length > 0) {
                         const lines = missing.map(
-                            m => `    • collection "${m.slug}" → table "${m.table}"`
+                            m => `    • collection "${m.slug}" → table "${m.table}"` +
+                                (m.foundIn.length > 0
+                                    ? ` — but a table of that name exists in ${m.foundIn.map(s => `"${s}"`).join(", ")}`
+                                    : "")
                         );
+                        // A table that exists under the same name in another
+                        // schema is not ordinary drift: it is almost always this
+                        // framework's own `search_path` hazard. Postgres resolves
+                        // unqualified SQL through `"$user", public`, and this
+                        // project creates a schema named `rebase` while every
+                        // template names the database role `rebase` too — so an
+                        // unqualified CREATE TABLE (a hand-written migration, the
+                        // SQL editor, drizzle-kit) lands in `rebase`, and the
+                        // runtime, which now pins `search_path=public`, cannot see
+                        // it. Say so, because "missing table" sends people to
+                        // re-run a push that will create a *second* copy.
+                        const misplaced = missing.filter(m => m.foundIn.length > 0);
+                        const misplacedHelp = misplaced.length === 0 ? [] : [
+                            "  Those tables exist — in the wrong schema. Unqualified SQL run by a",
+                            "  role whose name matches a schema (`rebase` is both, by default)",
+                            "  resolves through search_path's \"$user\" and creates there. Move them:",
+                            ...misplaced.map(m =>
+                                `      ALTER TABLE "${m.foundIn[0]}"."${m.table.split(".").pop()}" SET SCHEMA "${m.table.includes(".") ? m.table.split(".")[0] : "public"}";`
+                            ),
+                            "  and qualify the SQL that created them, or pin search_path in DATABASE_URL",
+                            "  (`?options=-c%20search_path%3Dpublic`).",
+                            ""
+                        ];
+                        // This runtime creates collection tables (and their RLS)
+                        // at boot unless REBASE_MIGRATE_ON_BOOT=none, so a drift
+                        // this late means that step was disabled, could not run,
+                        // or failed — the guidance names a path for both a managed
+                        // tenant (whose in-cluster database `pnpm db:push` cannot
+                        // reach) and a self-host. Naming only the pnpm scripts, as
+                        // this once did, told a managed operator to run a command
+                        // that structurally cannot touch their database.
                         logger.warn([
                             "",
-                            "┌──────────────────────────────────────────────────────────────┐",
-                            "│  ⚠️  SCHEMA DRIFT — Missing tables in database               │",
-                            "├──────────────────────────────────────────────────────────────┤",
-                            ...lines.map(l => `│ ${l.padEnd(60)}│`),
-                            "├──────────────────────────────────────────────────────────────┤",
-                            "│  Run one of:                                                 │",
-                            "│    pnpm db:push      (dev — fast, no migration files)        │",
-                            "│    pnpm db:migrate   (prod — creates migration files)        │",
-                            "└──────────────────────────────────────────────────────────────┘",
+                            "⚠️  SCHEMA DRIFT — the database is missing tables this backend serves:",
+                            ...lines,
+                            "",
+                            ...misplacedHelp,
+                            "  This runtime applies the collection schema at boot unless",
+                            "  REBASE_MIGRATE_ON_BOOT=none. Check the \"Collection schema\" / \"policies\"",
+                            "  log lines above — this drift means that step was off, skipped, or failed.",
+                            "    • Managed cloud: redeploy with REBASE_MIGRATE_ON_BOOT unset or",
+                            "      \"ensure\"; the runtime applies the schema to the tenant DB.",
+                            "      If the log above says the driver does not implement collection-table",
+                            "      creation, THIS driver is too old to do it. A driver is installed from",
+                            "      your bundle's dependencies, not supplied by the platform image, so a",
+                            "      newer runtime will not update it: bump \"@rebasepro/server-postgres\"",
+                            "      in your project's package.json and redeploy.",
+                            "    • Self-host: run `rebase db push` (dev) or `rebase db migrate` (prod)",
+                            "      against DATABASE_URL.",
                             ""
                         ].join("\n"));
                     }
@@ -711,7 +818,59 @@ schemaHealthCheck: () => probeAuthSchema(db, resolveAuthSchema(authCollection))
                 collections as Parameters<typeof ensureCollectionTables>[1],
                 log
             );
-            return { applied: plan.actions.length };
+            for (const failure of plan.failures) {
+                logger.warn(
+                    `🔗 [schema] Could not add foreign key "${failure.target}" — the column exists and the ` +
+                    `collection still serves, but rows are not policed by this constraint: ${failure.error}`
+                );
+            }
+            return { applied: plan.actions.length - plan.failures.length };
+        },
+
+        /**
+         * Apply the collections' RLS policies — ENABLE ROW LEVEL SECURITY and the
+         * `securityRules` compiled to `CREATE POLICY` — so a freshly provisioned
+         * database serves data instead of denying every user-context read.
+         *
+         * The companion to {@link ensureCollectionSchema}: that creates the
+         * tables, this makes them servable. Boot runs it *after* auth
+         * initialization, because the generated policies call `auth.uid()` /
+         * `auth.roles()`, and `CREATE POLICY` validates those functions exist.
+         *
+         * Runs through the same drizzle handle, one statement at a time (that
+         * handle speaks the extended query protocol, which rejects multi-command
+         * strings). Failures are per-table and non-fatal: a table left un-policed
+         * stays RLS-enabled, so it denies rather than leaks.
+         */
+        async ensureCollectionPolicies(
+            collections: unknown[],
+            driverResult: InitializedDriver,
+            log?: (message: string) => void
+        ): Promise<{ applied: number }> {
+            const internals = driverResult.internals as PostgresDriverInternals;
+            const { ensureCollectionPolicies } = await import("./schema/ensure-collection-policies");
+            const queryable = {
+                async query<T>(text: string): Promise<{ rows: T[] }> {
+                    const result = await internals.db.execute(sql.raw(text));
+                    const rows = (result as unknown as { rows?: T[] }).rows;
+                    return { rows: rows ?? (Array.isArray(result) ? (result as T[]) : []) };
+                }
+            };
+            const outcome = await ensureCollectionPolicies(
+                queryable,
+                collections as CollectionConfig[],
+                log
+            );
+
+            for (const skip of outcome.skipped) {
+                logger.warn(`🔐 [rls] Policies not applied to "${skip.table}": ${skip.reason}`);
+            }
+            for (const failure of outcome.failures) {
+                logger.warn(
+                    `🔐 [rls] Could not fully apply policies to "${failure.table}" — it stays locked (denies) until this is resolved: ${failure.error}`
+                );
+            }
+            return { applied: outcome.policiesApplied };
         },
 
         getAdmin(driverResult: InitializedDriver): DatabaseAdmin | undefined {

package/src/auth/services.ts

@@ -68,10 +68,13 @@ function getColumn(table: RebasePgTable | undefined, ...keys: string[]): RebaseP
  *
  * Whitespace goes too: a trailing space survives the fold and reproduces the
  * problem exactly.
+ *
+ * Re-exported rather than defined here: `@rebasepro/server` and
+ * `@rebasepro/server-mongo` write this column too, and a second copy of this
+ * rule is the defect it exists to prevent.
  */
-export function normalizeEmail<T>(email: T): T | string {
-    return typeof email === "string" ? email.trim().toLowerCase() : email;
-}
+import { normalizeEmail } from "@rebasepro/common";
+export { normalizeEmail };
 
 /**
  * PostgreSQL implementation of UserRepository.

package/src/backup/backup-cli.ts

@@ -100,6 +100,8 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
             "--out": String,
             "--exclude-schema": [String],
             "--no-owner": Boolean,
+            "--enable-row-security": Boolean,
+            "--row-security-role": String,
             "-o": "--out"
         },
         { argv: rawArgs.slice(2), permissive: true }
@@ -129,6 +131,23 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
     }
     logger.info(chalk.gray(`  Using pg_dump ${pf.toolMajor} against server ${pf.serverMajor}.`));
 
+    // Opt-in, and loud. With row security on, pg_dump stops refusing to read
+    // rows it cannot see and starts leaving them out — an exit-0 backup that
+    // is quietly short. Anyone choosing that should know they chose it.
+    const rowSecurity = args["--enable-row-security"]
+        ? { uid: "rebase-db-backup", roles: [args["--row-security-role"] || "admin"] }
+        : undefined;
+
+    if (rowSecurity) {
+        logger.warn("");
+        logger.warn(chalk.yellow("  ⚠  Dumping with row-level security ON."));
+        logger.warn(chalk.gray(`     Reading as roles [${rowSecurity.roles.join(", ")}], which satisfies the generated`));
+        logger.warn(chalk.gray("     `admin_full_access` policy. This backup contains exactly the rows those"));
+        logger.warn(chalk.gray("     policies admit — a table whose policies have no admin rule comes out short,"));
+        logger.warn(chalk.gray("     and pg_dump will not say so. Prefer granting the dumping role BYPASSRLS."));
+        logger.warn("");
+    }
+
     try {
         if (dest.kind === "local") {
             // Honour an explicit `…/name.dump` path; otherwise treat it as a
@@ -141,7 +160,8 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
                 fileName: explicitFile ? path.basename(dest.path) : undefined,
                 excludeSchemas: args["--exclude-schema"],
                 noOwner: args["--no-owner"],
-                inheritStdio: true
+                inheritStdio: true,
+                rowSecurity
             });
             await assertDumpValid(dump.localFile);
             logger.info("");
@@ -156,7 +176,8 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
                 dbName,
                 excludeSchemas: args["--exclude-schema"],
                 noOwner: args["--no-owner"],
-                inheritStdio: true
+                inheritStdio: true,
+                rowSecurity
             });
             try {
                 await assertDumpValid(dump.localFile);
@@ -395,6 +416,24 @@ ${chalk.green.bold("Options")}
   ${chalk.blue("--out, -o")} <dest>        Local path or s3://…/gs://… URL (default: ./backups)
   ${chalk.blue("--exclude-schema")} <s>    Exclude a schema (repeatable)
   ${chalk.blue("--no-owner")}              Omit ownership commands from the dump
+  ${chalk.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

package/src/backup/backup-service.ts

@@ -18,6 +18,9 @@ import {
     buildBackupFilename,
     buildPgDumpArgs,
     buildPgDumpallGlobalsArgs,
+    buildRowSecurityPgOptions,
+    diagnoseRowSecurityDumpFailure,
+    type RowSecurityIdentity,
     buildPgRestoreArgs,
     buildPgRestoreListArgs,
     checkToolServerCompatibility,
@@ -140,6 +143,15 @@ export async function createDump(opts: {
     inheritStdio?: boolean;
     includeGlobals?: boolean;
     env?: Record<string, string | undefined>;
+    /**
+     * Dump with row security left on, reading as this identity.
+     *
+     * The escape hatch for a managed Postgres, where the dumping role owns
+     * nothing and has no `BYPASSRLS`. Off by default, and deliberately so: with
+     * row security on, `pg_dump` stops erroring on rows it cannot see and
+     * simply omits them. See {@link RowSecurityIdentity}.
+     */
+    rowSecurity?: RowSecurityIdentity;
 }): Promise<BackupResult> {
     const env = opts.env ?? process.env;
     const bin = resolvePgBinary("pg_dump", env);
@@ -159,13 +171,34 @@ export async function createDump(opts: {
         connectionString: opts.connectionString,
         outFile: localFile,
         excludeSchemas: opts.excludeSchemas,
-        noOwner: opts.noOwner
+        noOwner: opts.noOwner,
+        rowSecurity: opts.rowSecurity
     });
 
-    await execa(bin, args, {
-        stdio: opts.inheritStdio ? "inherit" : "pipe",
-        env: { ...(env as Record<string, string>) }
-    });
+    // `PGOPTIONS` is the only way to set a GUC on a tool that takes no SQL.
+    // Built from the same object that added `--enable-row-security`, so the
+    // flag cannot travel without the identity that makes it safe.
+    const dumpEnv: Record<string, string> = { ...(env as Record<string, string>) };
+    if (opts.rowSecurity) {
+        dumpEnv.PGOPTIONS = [env.PGOPTIONS, buildRowSecurityPgOptions(opts.rowSecurity)]
+            .filter(Boolean).join(" ");
+    }
+
+    try {
+        await execa(bin, args, {
+            stdio: opts.inheritStdio ? "inherit" : "pipe",
+            env: dumpEnv
+        });
+    } catch (error) {
+        // The RLS failure names a table and no cause. Replace it with the
+        // cause and the two ways out; anything else is re-thrown untouched.
+        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 sizeBytes = fs.existsSync(localFile) ? fs.statSync(localFile).size : 0;
 

package/src/backup/pg-tools.ts

@@ -6,6 +6,8 @@
  * not require a database.
  */
 
+import { forLibpq } from "../utils/connection-string";
+
 /**
  * A parsed backup destination. `--out` (and the scheduled-backup config)
  * accepts either a local filesystem path or an object-storage URL.
@@ -171,6 +173,45 @@ export function joinStorageKey(prefix: string, fileName: string): string {
     return clean.length > 0 ? `${clean}/${fileName}` : fileName;
 }
 
+/**
+ * The identity `pg_dump` reads rows as, when row security is left on.
+ *
+ * Not optional, and that is the whole design. `pg_dump --enable-row-security`
+ * on its own is the dangerous command in this file: it turns the "query would
+ * be affected by row-level security policy" *error* into a dump that exits 0
+ * and is silently missing every row the dumping role's policies exclude. A
+ * backup that looks fine and restores most of your data is worse than one that
+ * refused to run.
+ *
+ * So the flag is unreachable without a subject to evaluate the policies
+ * against. Rebase's generated policies read `app.uid` and `app.user_roles`;
+ * supplying an admin role satisfies the `admin_full_access` rule and the dump
+ * sees everything that rule sees.
+ */
+export interface RowSecurityIdentity {
+    /** Written to `app.uid`. Any non-empty value — it is only an audit trail. */
+    uid: string;
+    /** Written to `app.user_roles`. Must include a role the policies admit. */
+    roles: string[];
+}
+
+/**
+ * `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.
+ */
+export function buildRowSecurityPgOptions(identity: RowSecurityIdentity): string {
+    const escape = (value: string) => 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`.
@@ -182,18 +223,70 @@ export function buildPgDumpArgs(opts: {
     excludeSchemas?: string[];
     /** Number of parallel jobs (directory format only; ignored for -Fc). */
     noOwner?: boolean;
+    /**
+     * Dump with row security on, as this identity. Omit — which is the default
+     * — and `pg_dump` errors rather than skipping rows it cannot see.
+     */
+    rowSecurity?: RowSecurityIdentity;
 }): string[] {
     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(opts.connectionString);
+    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.
+ */
+export function diagnoseRowSecurityDumpFailure(error: unknown): string | null {
+    const text = [
+        (error as { stderr?: unknown })?.stderr,
+        (error as { message?: unknown })?.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.
  */
@@ -211,7 +304,7 @@ export function buildPgRestoreArgs(opts: {
     exitOnError?: boolean;
     noOwner?: boolean;
 }): string[] {
-    const args = ["--format=custom", "--no-password", `--dbname=${opts.connectionString}`];
+    const args = ["--format=custom", "--no-password", `--dbname=${forLibpq(opts.connectionString)}`];
     if (opts.clean) {
         args.push("--clean", "--if-exists");
     }
@@ -255,7 +348,7 @@ export function buildPgDumpallGlobalsArgs(opts: {
         "--no-role-passwords",
         "--no-password",
         `--file=${opts.outFile}`,
-        `--dbname=${opts.connectionString}`
+        `--dbname=${forLibpq(opts.connectionString)}`
     ];
 }