@rebasepro/server-postgres 0.11.1-canary.gfd39654 → 0.12.1-canary.g009ed95

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();
+    }
+}

package/src/cli.ts

@@ -6,17 +6,19 @@ import fs from "fs";
 import { fileURLToPath } from "url";
 import { logger } from "@rebasepro/server";
 import {
+    diagnoseMissingBin,
     resolveLocalBin,
     getTableIncludes,
     getDevDatabaseUrl,
     ensureDevDatabaseExists,
     getTableExcludes,
-    ExcludeIntrospectionError
+    ExcludeIntrospectionError,
+    promptConfirm
 } from "./cli-helpers";
 import { checkDatabaseConnectivity, diagnoseDbError } from "./cli-errors";
+import { forLibpq } from "./utils/connection-string";
 import { AUTH_BOOTSTRAP_SQL } from "./schema/auth-bootstrap-sql";
 import { detectDestructiveStatements, decidePushSafety } from "./schema/destructive-sql";
-import readline from "readline";
 
 const __cliDirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -610,23 +612,6 @@ function timeAgo(date: Date): string {
 
 
 
-/**
- * Ask a yes/no question on an interactive terminal. Non-interactive shells
- * (CI, pipes, agents) can't answer, so this must only be reached after
- * {@link decidePushSafety} has already ruled that interactive confirmation is
- * possible.
- */
-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();
-    }
-}
-
 async function runAtlas(
     domain: "schema" | "migrate",
     args: string[],
@@ -635,9 +620,36 @@ async function runAtlas(
 ): Promise<string> {
     const atlasBin = resolveLocalBin("atlas");
     if (!atlasBin) {
-        logger.error(chalk.red("✗ Could not find atlas binary."));
-        const installCmd = "pnpm add -D @ariga/atlas";
-        logger.error(chalk.gray(`  Install it with: ${installCmd}`));
+        // Two very different causes, and the advice for one is a loop for the
+        // other — see `diagnoseMissingBin`. This used to say "Install it with:
+        // pnpm add -D @ariga/atlas" unconditionally, which is the exact command
+        // that produces the far more common of the two states.
+        logger.error(chalk.red("\n✗ The atlas binary is missing, so the schema cannot be applied.\n"));
+
+        if (diagnoseMissingBin("@ariga/atlas") === "build-script-blocked") {
+            logger.error(chalk.yellow("  @ariga/atlas IS installed — only its binary is missing.\n"));
+            logger.error(chalk.gray(
+                "  It downloads that binary in a `preinstall` script, and pnpm 10+ does not\n" +
+                "  run a dependency's scripts unless you allow it. The install still exits 0,\n" +
+                "  so the only sign is `Ignored build scripts: @ariga/atlas` in its output.\n"
+            ));
+            logger.error("  Fix it with either:\n");
+            logger.error(chalk.bold("    pnpm approve-builds\n"));
+            logger.error("  or, to record it in the project (what `rebase init` scaffolds):\n");
+            logger.error(chalk.bold(
+                "    // package.json\n" +
+                "    \"pnpm\": { \"onlyBuiltDependencies\": [\"@ariga/atlas\"] }\n"
+            ));
+            logger.error(chalk.gray("  Then re-run `pnpm install`.\n"));
+        } else {
+            logger.error(chalk.gray("  It is not installed in this project.\n"));
+            logger.error("  Install it with:\n");
+            logger.error(chalk.bold("    pnpm add -D @ariga/atlas\n"));
+            logger.error(chalk.gray(
+                "  If pnpm then reports `Ignored build scripts`, also run `pnpm approve-builds` —\n" +
+                "  the package carries a `preinstall` script that fetches the binary.\n"
+            ));
+        }
         process.exit(1);
     }
 
@@ -682,19 +694,25 @@ async function runAtlas(
     const devDatabaseUrl = getDevDatabaseUrl(databaseUrl);
     await ensureDevDatabaseExists(databaseUrl, devDatabaseUrl);
 
+    // Atlas speaks libpq, which rejects the `sslmode=no-verify` that
+    // node-postgres accepts — see `forLibpq`. Rewritten only for the argv, so
+    // everything above still connects with the URL as configured.
+    const atlasUrl = forLibpq(databaseUrl);
+    const atlasDevUrl = forLibpq(devDatabaseUrl);
+
     const atlasArgs = [domain, ...args];
 
     if (domain === "schema") {
         if (args.includes("apply")) {
-            atlasArgs.push("--url", databaseUrl, "--dev-url", devDatabaseUrl);
+            atlasArgs.push("--url", atlasUrl, "--dev-url", atlasDevUrl);
         } else if (args.includes("clean") || args.includes("inspect")) {
-            atlasArgs.push("--url", databaseUrl);
+            atlasArgs.push("--url", atlasUrl);
         }
     } else if (domain === "migrate") {
         if (args.includes("diff")) {
-            atlasArgs.push("--dev-url", devDatabaseUrl);
+            atlasArgs.push("--dev-url", atlasDevUrl);
         } else if (args.includes("apply") || args.includes("status")) {
-            atlasArgs.push("--url", databaseUrl, "--revisions-schema", "rebase");
+            atlasArgs.push("--url", atlasUrl, "--revisions-schema", "rebase");
             if (args.includes("apply")) {
                 atlasArgs.push("--allow-dirty");
             }

package/src/collections/buildRegistry.ts

@@ -9,7 +9,7 @@ import { assertRelationsResolve } from "./validate-relations";
 /**
  * Everything a registry is built from: the collections, and the drizzle schema
  * they are backed by. In BaaS mode all of it is introspected from the live
- * database; in CMS mode it comes from the config and the generated schema.
+ * database; when collections are declared it comes from the config and the generated schema.
  */
 export interface RegistrySchema {
     collections?: CollectionConfig[];

package/src/collections/validate-relations.ts

@@ -135,6 +135,21 @@ kind: relation.kind };
                             fix: `add the column, or set \`foreignKeyOnTarget\` to one of: ${quote(targetColumns)}`
                         });
                     }
+                    // `sourceKey` is the easiest of the two to put on the wrong
+                    // side — it is the only column in a `hasMany` that lives
+                    // here rather than on the target, and naming a target column
+                    // reads perfectly well right next to `foreignKeyOnTarget`.
+                    if (relation.sourceKey && !sourceColumns.has(relation.sourceKey)) {
+                        defects.push({
+                            ...at,
+                            problem: `\`sourceKey: "${relation.sourceKey}"\` is not a column on \`${sourceTableName}\``,
+                            fix: targetColumns.has(relation.sourceKey)
+                                ? `it is a column on the *target* table \`${targetTableName}\` — \`sourceKey\` names ` +
+                                  "the column on this collection that the target's foreign key points at, so it " +
+                                  `must be one of: ${quote(sourceColumns)}`
+                                : `add the column, or set \`sourceKey\` to one of: ${quote(sourceColumns)}`
+                        });
+                    }
                     break;
                 }
 

package/src/connection.ts

@@ -21,10 +21,19 @@ export interface PostgresPoolConfig {
     statementTimeout?: number;
     /** Enable TCP keep-alive (default: true) */
     keepAlive?: boolean;
+    /**
+     * `search_path` pinned on every connection (default: `"public"`).
+     *
+     * Pass `false` to send no `search_path` at all and inherit whatever the
+     * server/role defaults to. See {@link pinSearchPath} for why the default
+     * is not "inherit".
+     */
+    searchPath?: string | false;
 }
 
 const DEFAULT_POOL: Required<PostgresPoolConfig> = {
     max: 20,
+    searchPath: "public",
     idleTimeoutMillis: 30_000,
     connectionTimeoutMillis: 10_000,
     // The client-side read timeout MUST be comfortably above the server-side
@@ -43,6 +52,67 @@ const DEFAULT_POOL: Required<PostgresPoolConfig> = {
 /** ReadyForQuery status byte: `I` idle, `T` in transaction, `E` failed transaction. */
 const TX_IDLE = "I";
 
+/**
+ * Pin `search_path` into a connection string, so unqualified SQL resolves to a
+ * schema this framework chose rather than to one Postgres inferred.
+ *
+ * Postgres defaults `search_path` to `"$user", public`: the *first* candidate
+ * is a schema named after the connecting role. Rebase creates a schema called
+ * `rebase` (auth, history, api keys), and every template, compose file and
+ * deployment doc names the database role `rebase` too — so `$user` resolves to
+ * a schema that exists, and every unqualified statement lands there instead of
+ * in `public`. The generated Drizzle schema emits bare `pgTable("posts", …)`
+ * for any collection without an explicit `schema`, which makes the *runtime's*
+ * own reads and writes unqualified; a developer's raw `rebase.sql(...)`, the
+ * Studio SQL editor and any hand-written migration are unqualified too. The
+ * result is collection tables created in, and served from, `rebase`.
+ *
+ * Drizzle cannot express the fix on its side: `pgSchema("public")` throws by
+ * design ("just use pgTable() instead"), so there is no way to emit a
+ * public-qualified table from the generator. The pin has to live on the
+ * connection.
+ *
+ * Precedence is deliberate and verified against node-postgres: `options` in
+ * the connection string wins over the `options` field passed to `Pool`, so
+ * rewriting the URL — rather than setting the field — is what makes this
+ * authoritative. Two escape hatches survive it:
+ *
+ *  - an `options` that already mentions `search_path` is left untouched, so a
+ *    deployment that deliberately pins something else keeps it;
+ *  - `searchPath: false` (or an unparseable, non-URL connection string) sends
+ *    nothing and inherits the server default.
+ *
+ * Anything else in `options` (a `statement_timeout`, say) is preserved and the
+ * `search_path` flag is appended to it.
+ */
+export function pinSearchPath(connectionString: string, searchPath: string | false = "public"): string {
+    if (searchPath === false) return connectionString;
+
+    let url: URL;
+    try {
+        url = new URL(connectionString);
+    } catch {
+        // Key/value DSNs and anything else we cannot parse are returned as
+        // given: a connection that works unpinned beats one we corrupted.
+        return connectionString;
+    }
+    if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") return connectionString;
+
+    const existing = url.searchParams.get("options");
+    if (existing && /(^|\s)-c\s*search_path\s*=/.test(existing)) return connectionString;
+
+    const flag = `-c search_path=${searchPath}`;
+    url.searchParams.set("options", existing ? `${existing} ${flag}` : flag);
+    // Re-serialize by hand. `URLSearchParams` writes a space as `+`, which
+    // node-postgres happens to decode but libpq does not — and this same string
+    // is handed to `pg_dump`/`psql` for backups. Percent-encoding is the form
+    // both agree on, and is what the scaffolded `.env` already ships.
+    url.search = Array.from(url.searchParams.entries())
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+        .join("&");
+    return url.toString();
+}
+
 /**
  * Destroy pool clients that are released while still inside a transaction.
  *
@@ -108,6 +178,7 @@ export function createPostgresDatabaseConnection(
 ) {
     const opts = { ...DEFAULT_POOL,
 ...poolConfig };
+    connectionString = pinSearchPath(connectionString, opts.searchPath);
 
     const pgPoolConfig: PoolConfig = {
         connectionString,
@@ -159,6 +230,7 @@ export function createDirectDatabaseConnection(
         max: 5,
         ...poolConfig
     };
+    connectionString = pinSearchPath(connectionString, opts.searchPath);
 
     const pgPoolConfig: PoolConfig = {
         connectionString,
@@ -199,6 +271,7 @@ export function createReadReplicaConnection(
         max: 10,
         ...poolConfig
     };
+    connectionString = pinSearchPath(connectionString, opts.searchPath);
 
     const pgPoolConfig: PoolConfig = {
         connectionString,

package/src/data-transformer.ts

@@ -328,9 +328,15 @@ export async function parseDataFromServer<M extends Record<string, unknown>>(
                         const targetCollection = relation.target();
                         const targetTable = registry.getTable(getTableName(targetCollection));
                         const pks = getPrimaryKeys(collection, registry!);
-                        const currentId = buildCompositeId(data, pks);
-
-                        if (targetTable && currentId) {
+                        // What the target's foreign key holds. Ordinarily this
+                        // row's id; for a link on a natural key, the value of
+                        // the column it points at — which is on the row already,
+                        // so this costs nothing extra.
+                        const currentId = relation.sourceKey
+                            ? (data as Record<string, unknown>)[relation.sourceKey] as string | number | undefined
+                            : buildCompositeId(data, pks);
+
+                        if (targetTable && currentId !== undefined && currentId !== null && currentId !== "") {
                             const foreignKeyColumn = targetTable[relation.foreignKeyOnTarget as keyof typeof targetTable] as AnyPgColumn;
                             if (foreignKeyColumn) {
                                 // Query the target table to find row that references this row