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

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/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

package/src/databasePoolManager.ts

@@ -2,7 +2,7 @@ import { Pool } from "pg";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { logger } from "@rebasepro/server";
-import { guardPoolAgainstDirtyRelease } from "./connection";
+import { guardPoolAgainstDirtyRelease, pinSearchPath } from "./connection";
 
 export class DatabasePoolManager {
     private pools: Map<string, Pool> = new Map();
@@ -41,7 +41,10 @@ export class DatabasePoolManager {
         url.pathname = `/${databaseName}`;
 
         const pool = new Pool({
-            connectionString: url.toString(),
+            // Same pin as the primary pool: these are branch/multi-database
+            // connections to the *same* server, so they inherit the same
+            // `"$user"` hazard. See `pinSearchPath`.
+            connectionString: pinSearchPath(url.toString()),
             max: 10, // Default sensible limit, can be tuned later
             idleTimeoutMillis: 10000, // Reduced from 30000 for aggressive cleanup
             allowExitOnIdle: true // Prevent idle clients from hanging the Node.js process

package/src/schema/ensure-collection-policies.ts

@@ -0,0 +1,105 @@
+/**
+ * Applying a bundle's RLS policies to a database at boot, idempotently.
+ *
+ * ## Why this exists
+ *
+ * {@link ensureCollectionTables} creates the collection *tables* a managed
+ * runtime boots against, but a table with row-level security disabled and no
+ * policies is not servable: authenticated requests run as the restricted
+ * `rebase_user` role, so a read with no `SELECT` policy returns nothing (a
+ * public collection answered 401) and a write with no `INSERT`/`UPDATE` policy
+ * is denied. The policies live in the collections' `securityRules`; nothing at
+ * boot applied them. `rebase db push` does — but it drives Atlas against a
+ * local `DATABASE_URL`, and a managed tenant's database is reachable only from
+ * inside the cluster, by the runtime that is already connected to it. So the
+ * runtime is the only thing that *can* apply them, and this is where it does.
+ *
+ * ## Why this is safe to run on every boot
+ *
+ * Every statement is idempotent: `ENABLE ROW LEVEL SECURITY` is a no-op once
+ * enabled, and each policy is a `DROP POLICY IF EXISTS` immediately followed by
+ * a `CREATE POLICY`, so re-applying asserts exactly the declared state. It adds
+ * and replaces; it never drops data. (It does not *reconcile* — a policy a
+ * previous push left behind under an old name is not removed here; that stays a
+ * `db push` / `db migrate` concern, alongside destructive schema changes.)
+ *
+ * Unlike table creation, a failure here is not fatal: RLS stays enabled, so a
+ * table whose policies could not be applied fails **closed** (denies) rather
+ * than leaking rows. One collection's policy failing (e.g. a rule that
+ * references a table a real migration has not created yet) must not crash-loop
+ * the whole deployment and take the other collections' working routes down with
+ * it. Failures are reported loudly and per-table so the operator can see
+ * exactly which collection is not yet servable and why.
+ */
+import { type CollectionConfig } from "@rebasepro/types";
+import { planCollectionPolicies } from "./generate-postgres-ddl-logic";
+import { readExistingSchema, type Queryable } from "./ensure-collection-tables";
+
+export interface PolicyEnsureResult {
+    /** `CREATE POLICY` statements that ran successfully. */
+    policiesApplied: number;
+    /** Tables that had RLS enabled. */
+    tablesSecured: number;
+    /** Declared tables absent from the database — left to a real migration. */
+    skipped: { table: string; reason: string }[];
+    /** Tables whose RLS could not be fully applied (fail closed). */
+    failures: { table: string; error: string }[];
+}
+
+const isCreatePolicy = (statement: string): boolean => /^\s*CREATE POLICY/i.test(statement);
+
+/**
+ * Bring the declared collections' RLS policies up to date. Returns what it did.
+ *
+ * Only tables that already exist are touched: the boot-time table creator runs
+ * first, so anything still missing is a table this additive path is not allowed
+ * to create (a junction, or a relation left to a migration). Enabling RLS on a
+ * non-existent table would error, so those are recorded as skipped, not failed.
+ */
+export async function ensureCollectionPolicies(
+    client: Queryable,
+    collections: CollectionConfig[],
+    log?: (message: string) => void
+): Promise<PolicyEnsureResult> {
+    const result: PolicyEnsureResult = { policiesApplied: 0, tablesSecured: 0, skipped: [], failures: [] };
+
+    const plans = planCollectionPolicies(collections);
+    if (plans.length === 0) return result;
+
+    const schemas = Array.from(new Set(plans.map(p => p.schema)));
+    const existing = await readExistingSchema(client, schemas);
+
+    for (const plan of plans) {
+        if (!existing.tables.has(plan.qualified)) {
+            result.skipped.push({
+                table: plan.qualified,
+                reason: "table is not present in the database; create it with `rebase db push` / `rebase db migrate`"
+            });
+            continue;
+        }
+
+        try {
+            // Enable first: if a later policy statement fails, the table is left
+            // locked (deny-all for the user role) rather than open.
+            await client.query(plan.enableRls);
+            result.tablesSecured++;
+
+            let created = 0;
+            for (const statement of plan.policyStatements) {
+                await client.query(statement);
+                if (isCreatePolicy(statement)) {
+                    result.policiesApplied++;
+                    created++;
+                }
+            }
+            log?.(`${plan.qualified}: RLS enabled, ${created} policy(ies) applied`);
+        } catch (err) {
+            result.failures.push({
+                table: plan.qualified,
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+    }
+
+    return result;
+}

package/src/schema/ensure-collection-tables.test.ts

@@ -87,16 +87,112 @@ describe("planning an additive schema ensure", () => {
         expect(sql).not.toMatch(/NOT NULL/i);
     });
 
-    it("leaves relation columns to a real migration rather than adding them without their key", () => {
-        const withRelation = {
-            ...posts,
-            properties: {
-                ...(posts as unknown as { properties: Record<string, unknown> }).properties,
-                author: { name: "Author", type: "reference", target: () => posts }
+    // ── Relations ────────────────────────────────────────────────────────────
+    //
+    // These columns were once skipped outright, on the reasoning that a bare
+    // column without its foreign key would disagree with what `db push` later
+    // generated. On a managed tenant nothing pushes afterwards, so the table
+    // arrived without the column its own collection reads: every insert 400ed
+    // with `column "author_id" does not exist`. The answer is to emit the key
+    // too, from the same planner `db push` uses.
+
+    const authors = {
+        name: "Authors",
+        slug: "authors",
+        properties: {
+            id: { name: "ID", type: "string", isId: "uuid" },
+            name: { name: "Name", type: "string" }
+        }
+    } as unknown as CollectionConfig;
+
+    const postsWithAuthor = {
+        ...posts,
+        properties: {
+            ...(posts as unknown as { properties: Record<string, unknown> }).properties,
+            author: { name: "Author", type: "reference", path: "authors" }
+        }
+    } as unknown as CollectionConfig;
+
+    const tags = {
+        name: "Tags",
+        slug: "tags",
+        properties: {
+            id: { name: "ID", type: "number", isId: "increment" },
+            name: { name: "Name", type: "string" }
+        }
+    } as unknown as CollectionConfig;
+
+    const postsWithTags = {
+        ...posts,
+        properties: {
+            ...(posts as unknown as { properties: Record<string, unknown> }).properties,
+            tags: {
+                name: "Tags",
+                type: "relation",
+                relation: { kind: "manyToMany", target: () => tags, relationName: "tags" }
             }
-        } as unknown as CollectionConfig;
-        const plan = planCollectionSchemaEnsure([withRelation], withTable("public.posts", ["id"]));
-        expect(plan.actions.some(a => a.target.endsWith(".author"))).toBe(false);
+        }
+    } as unknown as CollectionConfig;
+
+    it("adds a reference column, and the foreign key that makes it one", () => {
+        const plan = planCollectionSchemaEnsure([postsWithAuthor, authors], withTable("public.posts", ["id"]));
+
+        expect(plan.actions.some(a => a.kind === "add-column" && a.target === "public.posts.author")).toBe(true);
+        const fk = plan.actions.find(a => a.kind === "add-constraint");
+        expect(fk?.target).toBe("public.posts.posts_author_fkey");
+        expect(fk?.sql).toMatch(/REFERENCES "public"\."authors" \("id"\)/);
+    });
+
+    it("orders every constraint after the columns and tables it depends on", () => {
+        const plan = planCollectionSchemaEnsure([postsWithAuthor, authors], empty());
+        const kinds = plan.actions.map(a => a.kind);
+        expect(kinds.lastIndexOf("add-column")).toBeLessThan(kinds.indexOf("add-constraint"));
+        expect(kinds.lastIndexOf("create-table")).toBeLessThan(kinds.indexOf("add-constraint"));
+    });
+
+    it("skips a foreign key the database already has, since ADD CONSTRAINT has no IF NOT EXISTS", () => {
+        const existing: ExistingSchema = {
+            tables: new Map([
+                ["public.posts", new Set(["id", "author"])],
+                ["public.authors", new Set(["id", "name"])]
+            ]),
+            enums: new Set(["public.posts_status"]),
+            constraints: new Set(["public.posts.posts_author_fkey"])
+        };
+        const plan = planCollectionSchemaEnsure([postsWithAuthor, authors], existing);
+        expect(plan.actions.some(a => a.kind === "add-constraint")).toBe(false);
+    });
+
+    it("creates the junction table behind a many-to-many, keyed on both endpoints", () => {
+        const plan = planCollectionSchemaEnsure([postsWithTags, tags], empty());
+        const junction = plan.actions.find(a => a.kind === "create-table" && a.target === "public.posts_tags");
+
+        expect(junction).toBeDefined();
+        // The endpoint key types have to match the primary keys they reference:
+        // posts is a uuid, tags an auto-increment integer.
+        expect(junction!.sql).toMatch(/"post_id" UUID NOT NULL/);
+        expect(junction!.sql).toMatch(/"tag_id" INTEGER NOT NULL/);
+        expect(junction!.sql).toMatch(/PRIMARY KEY \("post_id", "tag_id"\)/);
+
+        const fks = plan.actions.filter(a => a.kind === "add-constraint").map(a => a.target);
+        expect(fks).toContain("public.posts_tags.posts_tags_post_id_fkey");
+        expect(fks).toContain("public.posts_tags.posts_tags_tag_id_fkey");
+    });
+
+    it("leaves an existing junction table alone", () => {
+        const existing: ExistingSchema = {
+            tables: new Map([
+                ["public.posts", new Set(["id", "title", "views", "status"])],
+                ["public.tags", new Set(["id", "name"])],
+                ["public.posts_tags", new Set(["post_id", "tag_id"])]
+            ]),
+            enums: new Set(["public.posts_status"]),
+            constraints: new Set([
+                "public.posts_tags.posts_tags_post_id_fkey",
+                "public.posts_tags.posts_tags_tag_id_fkey"
+            ])
+        };
+        expect(planCollectionSchemaEnsure([postsWithTags, tags], existing).actions).toEqual([]);
     });
 });