@rebasepro/server-postgres 0.12.1-canary.gf5f1d39 → 0.13.0

package/src/auth/ensure-tables.ts

@@ -107,16 +107,38 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
                 ? "GENERATED ALWAYS AS IDENTITY"
                 : "DEFAULT gen_random_uuid()::text";
 
+        // Identifiers for the constraint and indexes reconciled further down.
+        // Derived from the resolved table name so two auth tables in different
+        // schemas cannot collide, and truncated to Postgres's 63-byte identifier
+        // limit here rather than letting the server truncate silently — the
+        // `IF NOT EXISTS` guards below have to compare against the same name
+        // Postgres actually stored, or they re-run forever.
+        const authIdentifier = (suffix: string) => `${resolvedTable}_${suffix}`.slice(0, 63);
+        const emailLengthConstraint = `"${authIdentifier("email_length_check")}"`;
+        const emailLowerUniqueIndex = authIdentifier("email_lower_key");
+        const verificationTokenIndex = authIdentifier("email_verification_token_idx");
+
+        // Every string column here is TEXT, deliberately. In Postgres VARCHAR(n)
+        // and TEXT are the same type with the same storage and the same
+        // performance; the only difference is a length check, and none of these
+        // columns wants one. The widths this table used to carry were inherited
+        // MySQL habit (255) and they were all wrong in the same direction —
+        // `password_hash VARCHAR(255)` against a 193-char scrypt string left 62
+        // characters of headroom in front of a KEY_LENGTH constant living in
+        // another package, and `photo_url VARCHAR(500)` rejected the `data:` URIs
+        // and long signed URLs that OAuth providers hand back. A limit worth
+        // having is a CHECK — alterable without a table rewrite, unlike a type
+        // modifier — which is why `email` has one and nothing else does.
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(usersTableName)} (
                 id ${sql.raw(userIdType)} PRIMARY KEY ${sql.raw(idDefault)},
-                email VARCHAR(255) UNIQUE NOT NULL,
-                display_name VARCHAR(255),
-                photo_url VARCHAR(500),
+                email TEXT NOT NULL CONSTRAINT ${sql.raw(emailLengthConstraint)} CHECK (length(email) <= 320),
+                display_name TEXT,
+                photo_url TEXT,
                 roles TEXT[] DEFAULT '{}' NOT NULL,
-                password_hash VARCHAR(255),
+                password_hash TEXT,
                 email_verified BOOLEAN DEFAULT FALSE NOT NULL,
-                email_verification_token VARCHAR(255),
+                email_verification_token TEXT,
                 email_verification_sent_at TIMESTAMP WITH TIME ZONE,
                 is_anonymous BOOLEAN DEFAULT FALSE NOT NULL,
                 metadata JSONB DEFAULT '{}' NOT NULL,
@@ -359,12 +381,12 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
         // statement that references it. `email` is deliberately absent: it has
         // existed since the first era and cannot be added NOT NULL safely.
         const userColumnBackfills = [
-            "display_name VARCHAR(255)",
-            "photo_url VARCHAR(500)",
+            "display_name TEXT",
+            "photo_url TEXT",
             "roles TEXT[] DEFAULT '{}' NOT NULL",
-            "password_hash VARCHAR(255)",
+            "password_hash TEXT",
             "email_verified BOOLEAN DEFAULT FALSE NOT NULL",
-            "email_verification_token VARCHAR(255)",
+            "email_verification_token TEXT",
             "email_verification_sent_at TIMESTAMP WITH TIME ZONE",
             "is_anonymous BOOLEAN DEFAULT FALSE NOT NULL",
             "metadata JSONB DEFAULT '{}' NOT NULL",
@@ -379,6 +401,139 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Col
             `);
         }
 
+        // Which of the columns below the table actually has. An adopted table —
+        // one this framework did not create, which the column-name resolution in
+        // `services.ts` exists to support — may be missing any of them, and every
+        // statement past this point has to tolerate that rather than abort the
+        // whole migration block.
+        const usersColumns = await db.execute(sql`
+            SELECT column_name, data_type
+            FROM information_schema.columns
+            WHERE table_schema = ${usersSchema} AND table_name = ${resolvedTable}
+        `);
+        const usersColumnTypes = new Map(
+            (usersColumns.rows as { column_name: string; data_type: string }[])
+                .map(row => [row.column_name, row.data_type])
+        );
+
+        // ── Migration: VARCHAR(n) → TEXT on the users string columns ────────
+        // Tables created before the widths came off still carry them. Postgres
+        // treats varchar(n) → text as binary-coercible with no stricter
+        // constraint, so this is a catalogue-only change: no table rewrite, no
+        // index rebuild, just a brief ACCESS EXCLUSIVE lock. Guarded on the
+        // current type so it runs once and is a pure catalogue read thereafter.
+        for (const column of ["email", "display_name", "photo_url", "password_hash", "email_verification_token"]) {
+            if (usersColumnTypes.get(column) !== "character varying") continue;
+            await db.execute(sql`
+                ALTER TABLE ${sql.raw(usersTableName)}
+                ALTER COLUMN ${sql.raw(`"${column}"`)} TYPE TEXT
+            `);
+            logger.info(`🔧 Widened ${usersTableName}.${column} from VARCHAR(n) to TEXT`);
+        }
+
+        // ── Migration: case-insensitive email identity ──────────────────────
+        // `getUserByEmail` has always searched `email.toLowerCase()` while the
+        // write path stored whatever it was handed, leaving normalisation to a
+        // convention every caller had to remember. A row that reached the table
+        // with mixed case is then invisible to every lookup — the account exists,
+        // login reports no such user, and the plain UNIQUE on `email` does not
+        // stop a second row differing only in case, because it compares bytes.
+        //
+        // Fixed on both sides: `mapPayload` now folds on write, and this index
+        // makes the database agree. A unique index on lower(email) is strictly
+        // stronger than the byte-exact UNIQUE that older tables carry, so the
+        // old constraint is left alone — it can no longer fire on anything the
+        // new one would allow.
+        //
+        // Deliberately no AUTH_SCHEMA_VERSION bump: a runtime that predates this
+        // migration keeps working against the migrated table (all of its own
+        // write paths already lower-cased), which is exactly the additive case
+        // the version stamp is documented not to cover.
+        if (usersColumnTypes.has("email")) {
+            const indexPresent = await db.execute(sql`
+                SELECT 1 FROM pg_class c
+                JOIN pg_namespace n ON n.oid = c.relnamespace
+                WHERE n.nspname = ${usersSchema} AND c.relname = ${emailLowerUniqueIndex} AND c.relkind = 'i'
+            `);
+            if (indexPresent.rows.length === 0) {
+                // Case-collisions already in the table would make the unique
+                // index impossible to build. Report them and leave the table
+                // alone: the next boot retries, so fixing the rows is all the
+                // operator has to do. Failing loudly beats folding the emails
+                // and letting CREATE INDEX pick which account survives.
+                const collisions = await db.execute(sql`
+                    SELECT lower(email) AS normalized, count(*)::int AS occurrences
+                    FROM ${sql.raw(usersTableName)}
+                    WHERE email IS NOT NULL
+                    GROUP BY lower(email)
+                    HAVING count(*) > 1
+                    LIMIT 10
+                `);
+                if (collisions.rows.length > 0) {
+                    const sample = (collisions.rows as { normalized: string; occurrences: number }[])
+                        .map(row => `${row.normalized} (×${row.occurrences})`)
+                        .join(", ");
+                    logger.error(
+                        `❌ Cannot enforce case-insensitive email uniqueness on ${usersTableName}: ` +
+                        `these addresses already exist more than once, differing only in case — ${sample}. ` +
+                        "Merge or delete the duplicates and restart; until then two accounts can share " +
+                        "one address and only the lower-cased one is reachable by login."
+                    );
+                } else {
+                    const folded = await db.execute(sql`
+                        UPDATE ${sql.raw(usersTableName)}
+                        SET email = lower(email)
+                        WHERE email IS NOT NULL AND email <> lower(email)
+                    `);
+                    if (folded.rowCount) {
+                        logger.info(`🔧 Lower-cased ${folded.rowCount} email address(es) in ${usersTableName}`);
+                    }
+                    await db.execute(sql`
+                        CREATE UNIQUE INDEX IF NOT EXISTS ${sql.raw(`"${emailLowerUniqueIndex}"`)}
+                        ON ${sql.raw(usersTableName)} (lower(email))
+                    `);
+                    logger.info(`✅ Email uniqueness on ${usersTableName} is now case-insensitive`);
+                }
+            }
+        }
+
+        // ── Migration: bound the email column's length ──────────────────────
+        // The only length limit on this table worth keeping. 320 is the RFC 5321
+        // maximum (64-char local part + @ + 255-char domain), and it matters here
+        // beyond tidiness: `email` carries a btree index, and a sufficiently long
+        // value fails index insertion with an error that says nothing about
+        // email. NOT VALID so an adopted table with a long row still migrates —
+        // it binds all new writes, which is the part that matters.
+        if (usersColumnTypes.has("email")) {
+            const checkPresent = await db.execute(sql`
+                SELECT 1 FROM pg_constraint c
+                JOIN pg_class t ON t.oid = c.conrelid
+                JOIN pg_namespace n ON n.oid = t.relnamespace
+                WHERE n.nspname = ${usersSchema}
+                  AND t.relname = ${resolvedTable}
+                  AND c.conname = ${authIdentifier("email_length_check")}
+            `);
+            if (checkPresent.rows.length === 0) {
+                await db.execute(sql`
+                    ALTER TABLE ${sql.raw(usersTableName)}
+                    ADD CONSTRAINT ${sql.raw(emailLengthConstraint)} CHECK (length(email) <= 320) NOT VALID
+                `);
+            }
+        }
+
+        // ── Index: email verification token lookups ─────────────────────────
+        // `getUserByVerificationToken` filters on this column, which had no
+        // index — every click of a verification link was a sequential scan of
+        // the whole users table. Partial, because the column is NULL for every
+        // user who is not mid-verification, which is nearly all of them.
+        if (usersColumnTypes.has("email_verification_token")) {
+            await db.execute(sql`
+                CREATE INDEX IF NOT EXISTS ${sql.raw(`"${verificationTokenIndex}"`)}
+                ON ${sql.raw(usersTableName)} (email_verification_token)
+                WHERE email_verification_token IS NOT NULL
+            `);
+        }
+
         // ── Migration: refresh_tokens become session-scoped, rotation-safe ──
         // Two shapes are reconciled here, on EVERY table named refresh_tokens
         // in whatever schema it lives (a database provisioned by an older era

package/src/auth/services.ts

@@ -54,6 +54,28 @@ function getColumn(table: RebasePgTable | undefined, ...keys: string[]): RebaseP
     return key ? table[key] : undefined;
 }
 
+/**
+ * The single definition of what an email address looks like in storage.
+ *
+ * Reads have always folded case; writes did not, and normalising was left to
+ * each caller. That asymmetry is only ever one forgotten `.toLowerCase()` away
+ * from a row no lookup can find — the account exists, every sign-in path
+ * reports no such user, and the byte-exact UNIQUE on the column does not stop a
+ * duplicate differing only in case. Applied on both sides here so the guarantee
+ * belongs to the repository rather than to its callers' discipline; the
+ * `lower(email)` unique index added in `ensureAuthTablesExist` is the database
+ * half of the same rule.
+ *
+ * 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.
+ */
+import { normalizeEmail } from "@rebasepro/common";
+export { normalizeEmail };
+
 /**
  * PostgreSQL implementation of UserRepository.
  * Handles all user-related database operations using Drizzle ORM.
@@ -184,7 +206,7 @@ export class UserService implements UserRepository {
         const metadataKey = getColumnKey(this.usersTable, "metadata") || "metadata";
 
         if ("id" in data) payload[idKey] = data.id;
-        if ("email" in data) payload[emailKey] = data.email;
+        if ("email" in data) payload[emailKey] = normalizeEmail(data.email);
         if ("passwordHash" in data) payload[passwordHashKey] = data.passwordHash;
         if ("displayName" in data) payload[displayNameKey] = data.displayName;
         if ("photoUrl" in data) payload[photoUrlKey] = data.photoUrl;
@@ -244,7 +266,7 @@ export class UserService implements UserRepository {
     async getUserByEmail(email: string): Promise<UserData | null> {
         const emailCol = getColumn(this.usersTable, "email");
         if (!emailCol) return null;
-        const [row] = await this.db.select().from(this.usersTable).where(eq(emailCol, email.toLowerCase()));
+        const [row] = await this.db.select().from(this.usersTable).where(eq(emailCol, normalizeEmail(email)));
         return row ? this.mapRowToUser(row as Record<string, unknown>) : null;
     }
 

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)}`
     ];
 }
 

package/src/cli-helpers.ts

@@ -2,6 +2,8 @@ import { isManyToMany } from "@rebasepro/types";
 import path from "path";
 import fs from "fs";
 import { execSync } from "child_process";
+import { createRequire } from "module";
+import readline from "readline";
 import { pathToFileURL } from "url";
 import chalk from "chalk";
 import { logger } from "@rebasepro/server";
@@ -10,6 +12,49 @@ import { moduleDir as __helpersDirname } from "./module-dir";
 
 
 
+/**
+ * Why is a dependency's binary missing — never installed, or installed with its
+ * build script blocked?
+ *
+ * These need opposite advice, and getting it wrong is not a cosmetic miss. pnpm
+ * 10+ refuses to run a dependency's lifecycle scripts unless it is allowlisted
+ * (`pnpm.onlyBuiltDependencies`, or `allowBuilds` in `pnpm-workspace.yaml`).
+ * `@ariga/atlas` downloads its platform binary in `preinstall`, so a blocked
+ * script leaves a state that looks like a successful install: the package is on
+ * disk with its `install.js` and `package.json`, `node_modules/.bin` is empty,
+ * the install exits 0, and the only signal is `ERR_PNPM_IGNORED_BUILDS` several
+ * screens up.
+ *
+ * Telling somebody in that state to install the package again sends them round
+ * the same loop forever — the add succeeds, the script is blocked again,
+ * nothing changes. Verified by doing it: `pnpm add @ariga/atlas` into a bare
+ * project yields exactly this, three "Failed to create bin … ENOENT" warnings
+ * and no binary.
+ *
+ * Resolution is attempted from the user's project first and this package
+ * second, matching the order {@link resolveLocalBin} searches — the driver may
+ * be installed a level up from where the command runs.
+ */
+export function diagnoseMissingBin(packageName: string): "not-installed" | "build-script-blocked" {
+    const bases = [
+        pathToFileURL(path.join(process.cwd(), "package.json")),
+        pathToFileURL(path.join(__helpersDirname, "package.json"))
+    ];
+
+    for (const base of bases) {
+        try {
+            // `package.json` rather than the package root: a package with an
+            // `exports` map that omits `.` is unresolvable by name even when it
+            // is perfectly installed, which would misreport it as absent.
+            createRequire(base).resolve(`${packageName}/package.json`);
+            return "build-script-blocked";
+        } catch {
+            // Try the next base.
+        }
+    }
+    return "not-installed";
+}
+
 export function resolveLocalBin(binName: string): string | null {
     // Try to find node_modules/.bin upwards from __helpersDirname first (package-relative)
     let dir = __helpersDirname;
@@ -232,3 +277,28 @@ export async function getTableExcludes(
     return excludes;
 }
 
+
+/**
+ * Ask a yes/no question on an interactive terminal.
+ *
+ * The `isTTY` guard is the contract, not an optimisation: non-interactive
+ * shells (CI, pipes, agents) can never answer, and `readline` on a
+ * non-TTY stdin resolves with whatever the pipe happens to contain — or never
+ * resolves at all. Returning false there is what makes an unattended
+ * `db push` abort instead of auto-confirming a destructive change. Callers
+ * should already have gone through {@link decidePushSafety}, which decides
+ * whether interactive confirmation is even possible; this is the backstop.
+ *
+ * Lives here rather than in cli.ts so it is reachable from a test — cli.ts uses
+ * `import.meta` and cannot be imported by the jest runner.
+ */
+export async function promptConfirm(question: string): Promise<boolean> {
+    if (!process.stdin.isTTY) return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer: string = await new Promise((resolve) => rl.question(question, resolve));
+        return /^y(es)?$/i.test(answer.trim());
+    } finally {
+        rl.close();
+    }
+}