@rebasepro/server-postgres 0.12.1-canary.gf5f1d39 → 0.13.1-canary.g06dbe5b

package/src/schema/doctor.ts

@@ -15,9 +15,9 @@ import chalk from "chalk";
 import { CollectionConfig, isPostgresCollectionConfig, Property, NumberProperty, StringProperty, DateProperty, ArrayProperty, MapProperty, RelationProperty, type ResolvedManyToMany, type ResolvedBelongsTo, isManyToMany } from "@rebasepro/types";
 import { generateSchema } from "./generate-drizzle-schema-logic";
 import { generateTypedefs } from "@rebasepro/codegen";
-import { getTableName, resolveCollectionRelations, findRelation } from "@rebasepro/common";
+import { getTableName, resolveCollectionRelations, findRelation, relationalCollections } from "@rebasepro/common";
 import { toSnakeCase } from "@rebasepro/utils";
-import { logger, loadCollectionsFromDirectory } from "@rebasepro/server";
+import { loadCollectionsFromDirectory } from "@rebasepro/server";
 
 /**
  * Resolve the SQL column name for a property.
@@ -33,11 +33,27 @@ const resolveColumnName = (propName: string, prop?: Property | null): string =>
 
 // ── Types ────────────────────────────────────────────────────────────────
 
+/**
+ * The report is CLI output, not application logging.
+ *
+ * `logger.info` is gated by `LOG_LEVEL`, which is a documented setting and
+ * ships in the scaffold's own `.env.example`: a developer who quietened their
+ * dev server with `LOG_LEVEL=warn` got a `rebase doctor` that printed nothing
+ * at all and still exited 1, with no way to tell a failing run from a crashed
+ * one. At the default level every line of the ASCII box arrived with
+ * `ℹ️ [INFO] ` glued to the front of it, and under `NODE_ENV=production` the
+ * whole report became JSON log records with the chalk escapes inside.
+ * `packages/cli` writes all of its output this way for the same reason.
+ */
+const out = (line = ""): void => {
+    console.log(line);
+};
+
 export type IssueSeverity = "error" | "warning" | "info";
 
 export interface DoctorIssue {
     severity: IssueSeverity;
-    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key" | "sdk_stale" | "sdk_not_generated";
+    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key" | "sdk_stale" | "sdk_not_generated" | "sdk_ungeneratable";
     table?: string;
     column?: string;
     expected?: string;
@@ -46,11 +62,27 @@ export interface DoctorIssue {
     fix: string;
 }
 
+export interface DoctorPhase {
+    passed: boolean;
+    issues: DoctorIssue[];
+    /**
+     * Why this phase never ran, when it did not.
+     *
+     * A check that did not happen is a third state, not a passing one. While a
+     * skipped phase initialised to `{ passed: true, issues: [] }` it rendered as
+     * `✅ Collections → Database: In sync` and counted towards
+     * `✓ All schemas are in sync!` — so a project whose connection string was
+     * spelled `POSTGRES_URL`, or a CI job that never exported one, got two green
+     * ticks and exit 0 against a database with no tables in it.
+     */
+    skipped?: string;
+}
+
 export interface DoctorReport {
-    collectionsToSchema: { passed: boolean; issues: DoctorIssue[] };
-    collectionsToSdk: { passed: boolean; issues: DoctorIssue[] };
-    schemaToDatabase: { passed: boolean; issues: DoctorIssue[] };
-    summary: { passed: number; warnings: number; errors: number };
+    collectionsToSchema: DoctorPhase;
+    collectionsToSdk: DoctorPhase;
+    schemaToDatabase: DoctorPhase;
+    summary: { passed: number; skipped: number; warnings: number; errors: number };
 }
 
 // ── Column type mapping (mirrors generate-drizzle-schema-logic.ts) ───────
@@ -149,7 +181,7 @@ export async function loadCollections(collectionsPath: string): Promise<Collecti
 export async function checkCollectionsVsSchema(
     collections: CollectionConfig[],
     schemaFilePath: string
-): Promise<{ passed: boolean; issues: DoctorIssue[] }> {
+): Promise<DoctorPhase> {
     const issues: DoctorIssue[] = [];
 
     // Check if schema file exists
@@ -164,8 +196,10 @@ export async function checkCollectionsVsSchema(
 issues };
     }
 
-    // Re-generate schema in-memory and compare with file on disk
-    const postgresCollections = collections.filter(isPostgresCollectionConfig);
+    // Re-generate schema in-memory and compare with file on disk. Only the
+    // collections the generator itself will emit — a Firestore collection has
+    // no table in the generated file and must not be reported as missing one.
+    const postgresCollections = relationalCollections(collections);
     if (postgresCollections.length === 0) {
         return { passed: true,
 issues };
@@ -208,7 +242,7 @@ issues };
 export async function checkCollectionsVsSdk(
     collections: CollectionConfig[],
     sdkFilePath: string
-): Promise<{ passed: boolean; issues: DoctorIssue[] }> {
+): Promise<DoctorPhase> {
     const issues: DoctorIssue[] = [];
 
     // The typed SDK is opt-in — nothing in a scaffolded project imports it until
@@ -248,12 +282,27 @@ issues };
         }
     } catch (err: unknown) {
         const message = err instanceof Error ? err.message : String(err);
-        issues.push({
-            severity: "warning",
-            category: "sdk_stale",
-            message: `Could not regenerate SDK types for comparison: ${message}`,
-            fix: "Run `rebase generate-sdk` to verify"
-        });
+
+        // A `CodegenError` is not "the comparison did not run" — it is the
+        // schema saying it cannot produce a valid typed client at all, most
+        // often two slugs collapsing onto one accessor. Reporting that as a
+        // warning about staleness described the wrong problem and pointed at a
+        // command that would fail the same way.
+        if (err instanceof Error && err.name === "CodegenError") {
+            issues.push({
+                severity: "error",
+                category: "sdk_ungeneratable",
+                message: `The typed SDK cannot be generated from these collections: ${message}`,
+                fix: "Fix the collection definitions named above, then run `rebase generate-sdk`"
+            });
+        } else {
+            issues.push({
+                severity: "warning",
+                category: "sdk_stale",
+                message: `Could not regenerate SDK types for comparison: ${message}`,
+                fix: "Run `rebase generate-sdk` to verify"
+            });
+        }
     }
 
     return { passed: issues.length === 0,
@@ -280,7 +329,7 @@ interface DbEnumValue {
 export async function checkCollectionsVsDatabase(
     collections: CollectionConfig[],
     databaseUrl: string
-): Promise<{ passed: boolean; issues: DoctorIssue[] }> {
+): Promise<DoctorPhase> {
     const issues: DoctorIssue[] = [];
 
     // Dynamic import to avoid loading pg when not needed
@@ -292,7 +341,7 @@ export async function checkCollectionsVsDatabase(
     const schemas = Array.from(new Set([
         "public",
         "rebase",
-        ...collections
+        ...relationalCollections(collections)
             .filter(isPostgresCollectionConfig)
             .map(c => c.schema)
             .filter((s): s is string => !!s)
@@ -383,7 +432,7 @@ export async function checkCollectionsVsDatabase(
 
         // ── Compare each collection against the database ─────────────────
 
-        const postgresCollections = collections.filter(isPostgresCollectionConfig);
+        const postgresCollections = relationalCollections(collections);
 
         for (const collection of postgresCollections) {
             const tableName = getTableName(collection);
@@ -595,96 +644,99 @@ issues };
 // ── Report Rendering ─────────────────────────────────────────────────────
 
 export function renderReport(report: DoctorReport): void {
-    logger.info("");
-    logger.info(chalk.bold("  🩺 Rebase Schema Doctor"));
-    logger.info(chalk.gray("  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
-    logger.info("");
+    out();
+    out(chalk.bold("  🩺 Rebase Schema Doctor"));
+    out(chalk.gray("  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
+    out();
 
     // Phase 1
-    renderPhase(
-        "Collections → Generated Schema",
-        report.collectionsToSchema.passed,
-        report.collectionsToSchema.issues
-    );
+    renderPhase("Collections → Generated Schema", report.collectionsToSchema);
 
     // Phase 2
-    renderPhase(
-        "Collections → Database",
-        report.schemaToDatabase.passed,
-        report.schemaToDatabase.issues
-    );
+    renderPhase("Collections → Database", report.schemaToDatabase);
 
     // Phase 3
-    renderPhase(
-        "Collections → SDK Types",
-        report.collectionsToSdk.passed,
-        report.collectionsToSdk.issues
-    );
+    renderPhase("Collections → SDK Types", report.collectionsToSdk);
 
     // Summary
-    logger.info(chalk.gray("  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
-    const { passed, warnings, errors } = report.summary;
+    out(chalk.gray("  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
+    const { passed, skipped, warnings, errors } = report.summary;
 
     const parts: string[] = [];
     parts.push(chalk.green(`${passed} passed`));
+    if (skipped > 0) parts.push(chalk.yellow(`${skipped} skipped`));
     if (warnings > 0) parts.push(chalk.yellow(`${warnings} warnings`));
     if (errors > 0) parts.push(chalk.red(`${errors} errors`));
 
-    logger.info(`  Summary: ${parts.join(", ")}`);
-    logger.info("");
+    out(`  Summary: ${parts.join(", ")}`);
+    out();
 
     if (errors > 0) {
-        logger.info(chalk.red.bold("  ✗ Schema drift detected. Run the suggested fixes above."));
+        out(chalk.red.bold("  ✗ Schema drift detected. Run the suggested fixes above."));
     } else if (warnings > 0) {
-        logger.info(chalk.yellow.bold("  ⚠ Minor issues detected. Consider running the suggested fixes."));
+        out(chalk.yellow.bold("  ⚠ Minor issues detected. Consider running the suggested fixes."));
+    } else if (skipped > 0) {
+        // Never "all schemas are in sync" off the back of a check that did not
+        // run: a clean bill of health has to come from measurement.
+        out(chalk.yellow.bold(`  ⚠ Nothing wrong in the checks that ran, but ${skipped} did not run — this is not a clean bill of health.`));
     } else {
-        logger.info(chalk.green.bold("  ✓ All schemas are in sync!"));
+        out(chalk.green.bold("  ✓ All schemas are in sync!"));
     }
-    logger.info("");
+    out();
 }
 
-function renderPhase(label: string, passed: boolean, issues: DoctorIssue[]): void {
+function renderPhase(label: string, phase: DoctorPhase): void {
+    // A phase that never ran gets its own marker and its reason. It is neither
+    // "In sync" nor a drift report; conflating it with the former is what let
+    // doctor certify a database it had not opened.
+    if (phase.skipped) {
+        out(`  ${chalk.yellow("⏭")}  ${label}: ${chalk.yellow(`skipped (${phase.skipped})`)}`);
+        out();
+        return;
+    }
+
+    const issues = phase.issues;
     const errorCount = issues.filter((i) => i.severity === "error").length;
     const warnCount = issues.filter((i) => i.severity === "warning").length;
     const infoIssues = issues.filter((i) => i.severity === "info");
 
     // Informational notes don't make a phase unhealthy, so key the header off
-    // real problems rather than `passed` alone.
+    // real problems rather than `phase.passed` alone.
     if (errorCount === 0 && warnCount === 0) {
-        logger.info(`  ${chalk.green("✅")} ${label}: ${chalk.green("In sync")}`);
+        out(`  ${chalk.green("✅")} ${label}: ${chalk.green("In sync")}`);
     } else {
         const parts: string[] = [];
         if (errorCount > 0) parts.push(`${errorCount} error${errorCount > 1 ? "s" : ""}`);
         if (warnCount > 0) parts.push(`${warnCount} warning${warnCount > 1 ? "s" : ""}`);
-        logger.info(`  ${chalk.yellow("⚠️")}  ${label}: ${chalk.yellow(parts.join(", "))}`);
+        out(`  ${chalk.yellow("⚠️")}  ${label}: ${chalk.yellow(parts.join(", "))}`);
     }
-    logger.info("");
+    out();
 
     // Notes render as a quiet one-liner, not a full drift box.
     for (const issue of infoIssues) {
         const fixPart = issue.fix ? chalk.gray(` — ${issue.fix}`) : "";
-        logger.info(`  ${chalk.gray("ℹ")} ${chalk.gray(issue.message)}${fixPart}`);
-        logger.info("");
+        out(`  ${chalk.gray("ℹ")} ${chalk.gray(issue.message)}${fixPart}`);
+        out();
     }
 
     for (const issue of issues.filter((i) => i.severity !== "info")) {
         const severityIcon = issue.severity === "error" ? chalk.red("✗") : chalk.yellow("⚠");
         const categoryLabel = formatCategory(issue.category);
-        logger.info(`  ${chalk.gray("┌─")} ${severityIcon} ${chalk.bold(categoryLabel)} ${chalk.gray("─".repeat(Math.max(0, 42 - categoryLabel.length)))}`);
+        out(`  ${chalk.gray("┌─")} ${severityIcon} ${chalk.bold(categoryLabel)} ${chalk.gray("─".repeat(Math.max(0, 42 - categoryLabel.length)))}`);
 
         if (issue.table) {
             const colPart = issue.column ? ` │ Column: ${chalk.cyan(issue.column)}` : "";
-            logger.info(`  ${chalk.gray("│")} Table: ${chalk.cyan(issue.table)}${colPart}`);
+            out(`  ${chalk.gray("│")} Table: ${chalk.cyan(issue.table)}${colPart}`);
         }
 
         if (issue.expected && issue.actual) {
-            logger.info(`  ${chalk.gray("│")} Expected: ${chalk.green(issue.expected)} │ Actual: ${chalk.red(issue.actual)}`);
+            out(`  ${chalk.gray("│")} Expected: ${chalk.green(issue.expected)} │ Actual: ${chalk.red(issue.actual)}`);
         }
 
-        logger.info(`  ${chalk.gray("│")} ${issue.message}`);
-        logger.info(`  ${chalk.gray("│")} Fix: ${chalk.blue(issue.fix)}`);
-        logger.info(`  ${chalk.gray("└" + "─".repeat(48))}`);
-        logger.info("");
+        out(`  ${chalk.gray("│")} ${issue.message}`);
+        out(`  ${chalk.gray("│")} Fix: ${chalk.blue(issue.fix)}`);
+        out(`  ${chalk.gray("└" + "─".repeat(48))}`);
+        out();
     }
 }
 
@@ -699,7 +751,8 @@ function formatCategory(cat: DoctorIssue["category"]): string {
         enum_value_mismatch: "Enum Value Mismatch",
         missing_foreign_key: "Missing Foreign Key",
         sdk_stale: "Stale SDK Types",
-        sdk_not_generated: "SDK Types Not Generated"
+        sdk_not_generated: "SDK Types Not Generated",
+        sdk_ungeneratable: "SDK Cannot Be Generated"
     };
     return labels[cat];
 }
@@ -712,38 +765,44 @@ export async function runDoctor(options: {
     sdkPath: string;
     databaseUrl?: string;
 }): Promise<DoctorReport> {
-    logger.info("");
-    logger.info(chalk.bold("  🩺 Loading collections..."));
+    out();
+    out(chalk.bold("  🩺 Loading collections..."));
     const collections = await loadCollections(options.collectionsPath);
     if (collections.length === 0) {
-        logger.error(chalk.red("  ✗ No collections found."));
+        console.error(chalk.red("  ✗ No collections found."));
         process.exit(1);
     }
-    logger.info(chalk.gray(`  Found ${collections.length} collection(s)`));
-    logger.info("");
+    out(chalk.gray(`  Found ${collections.length} collection(s)`));
+    out();
 
     // Phase 1: Collections ↔ Generated Schema
-    logger.info(chalk.gray("  Checking Collections → Generated Schema..."));
+    out(chalk.gray("  Checking Collections → Generated Schema..."));
     const collectionsToSchema = await checkCollectionsVsSchema(collections, options.schemaPath);
 
     // Phase 2: Collections ↔ Database (only if we have a DATABASE_URL)
-    let schemaToDatabase: { passed: boolean; issues: DoctorIssue[] } = { passed: true,
-issues: [] };
+    let schemaToDatabase: DoctorPhase;
     if (options.databaseUrl) {
-        logger.info(chalk.gray("  Checking Collections → Database..."));
+        out(chalk.gray("  Checking Collections → Database..."));
         schemaToDatabase = await checkCollectionsVsDatabase(collections, options.databaseUrl);
     } else {
-        logger.info(chalk.yellow("  ⚠ DATABASE_URL not set — skipping database comparison."));
-        logger.info(chalk.gray("    Set DATABASE_URL in your .env to enable full drift detection."));
+        // Not `{ passed: true }`: see DoctorPhase.skipped.
+        schemaToDatabase = { passed: false,
+issues: [],
+skipped: "DATABASE_URL not set" };
+        out(chalk.yellow("  ⚠ DATABASE_URL not set — skipping database comparison."));
+        out(chalk.gray("    Set DATABASE_URL in your .env to enable full drift detection."));
     }
 
     // Phase 3: Collections ↔ SDK Types
-    logger.info(chalk.gray("  Checking Collections → SDK Types..."));
+    out(chalk.gray("  Checking Collections → SDK Types..."));
     const collectionsToSdk = await checkCollectionsVsSdk(collections, options.sdkPath);
 
-    const allIssues = [...collectionsToSchema.issues, ...schemaToDatabase.issues, ...collectionsToSdk.issues];
+    const phases = [collectionsToSchema, schemaToDatabase, collectionsToSdk];
+    const allIssues = phases.flatMap((p) => p.issues);
     const summary = {
-        passed: [collectionsToSchema, schemaToDatabase, collectionsToSdk].filter((p) => p.passed).length,
+        // A skipped phase is not a passing one, however few issues it collected.
+        passed: phases.filter((p) => p.passed && !p.skipped).length,
+        skipped: phases.filter((p) => p.skipped).length,
         warnings: allIssues.filter((i) => i.severity === "warning").length,
         errors: allIssues.filter((i) => i.severity === "error").length
     };

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