@rebasepro/server-postgres 0.12.0 → 0.12.1-canary.g35be8cb

package/src/auth/services.ts

@@ -54,6 +54,25 @@ 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.
+ */
+export function normalizeEmail<T>(email: T): T | string {
+    return typeof email === "string" ? email.trim().toLowerCase() : email;
+}
+
 /**
  * PostgreSQL implementation of UserRepository.
  * Handles all user-related database operations using Drizzle ORM.
@@ -184,7 +203,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 +263,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/schema/auth-schema.ts

@@ -1,8 +1,19 @@
-import { pgSchema, pgTable, varchar, uuid, timestamp, boolean, jsonb, text, unique, index } from "drizzle-orm/pg-core";
+import { pgSchema, pgTable, uuid, timestamp, boolean, jsonb, text, unique, index } from "drizzle-orm/pg-core";
 import { relations } from "drizzle-orm";
 
 /**
  * Factory function to dynamically create the auth tables bound to the specified schema names.
+ *
+ * This module builds queries; it does not create tables. `ensureAuthTablesExist`
+ * owns the DDL, which makes everything here a *claim* about a database it cannot
+ * enforce — and the claims drifted. Every column below was declared
+ * `varchar(n)` while the DDL created it as `TEXT`: `user_agent` as varchar(500),
+ * `ip_address` as varchar(45), `secret_encrypted` as varchar(500), every
+ * `token_hash` as varchar(255). None of it was true of any database this
+ * framework ever provisioned. Harmless at runtime — drizzle does not enforce a
+ * length client-side, so the widths only ever misled the next reader — but a
+ * schema module that describes columns that do not exist is worse than no
+ * schema module. They are `text` here now because they are TEXT there.
  */
 export function createAuthSchema(usersSchemaName = "rebase") {
     const usersSchema = usersSchemaName === "public" ? null : pgSchema(usersSchemaName);
@@ -15,12 +26,12 @@ export function createAuthSchema(usersSchemaName = "rebase") {
      */
     const users = usersTableCreator("users", {
         id: uuid("id").defaultRandom().primaryKey(),
-        email: varchar("email", { length: 255 }).notNull().unique(),
-        passwordHash: varchar("password_hash", { length: 255 }), // NULL for OAuth-only users
-        displayName: varchar("display_name", { length: 255 }),
-        photoUrl: varchar("photo_url", { length: 500 }),
+        email: text("email").notNull().unique(),
+        passwordHash: text("password_hash"), // NULL for OAuth-only users
+        displayName: text("display_name"),
+        photoUrl: text("photo_url"),
         emailVerified: boolean("email_verified").default(false).notNull(),
-        emailVerificationToken: varchar("email_verification_token", { length: 255 }),
+        emailVerificationToken: text("email_verification_token"),
         emailVerificationSentAt: timestamp("email_verification_sent_at"),
         isAnonymous: boolean("is_anonymous").default(false).notNull(),
         roles: text("roles").array().default([]).notNull(),
@@ -65,7 +76,7 @@ export function createAuthSchema(usersSchemaName = "rebase") {
         id: uuid("id").defaultRandom().primaryKey(),
         uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
         sessionId: uuid("session_id").defaultRandom().notNull(),
-        tokenHash: varchar("token_hash", { length: 255 }).notNull().unique(),
+        tokenHash: text("token_hash").notNull().unique(),
         expiresAt: timestamp("expires_at").notNull(),
         revoked: boolean("revoked").default(false).notNull(),
         rotatedAt: timestamp("rotated_at"),
@@ -76,8 +87,8 @@ export function createAuthSchema(usersSchemaName = "rebase") {
          * that rotates immediately after it.
          */
         sessionStartedAt: timestamp("session_started_at").defaultNow().notNull(),
-        userAgent: varchar("user_agent", { length: 500 }),
-        ipAddress: varchar("ip_address", { length: 45 }),
+        userAgent: text("user_agent"),
+        ipAddress: text("ip_address"),
         createdAt: timestamp("created_at").defaultNow().notNull()
     }, (table) => ({
         sessionIdx: index("idx_refresh_tokens_session").on(table.sessionId)
@@ -89,7 +100,7 @@ export function createAuthSchema(usersSchemaName = "rebase") {
     const passwordResetTokens = tableCreator("password_reset_tokens", {
         id: uuid("id").defaultRandom().primaryKey(),
         uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
-        tokenHash: varchar("token_hash", { length: 255 }).notNull().unique(),
+        tokenHash: text("token_hash").notNull().unique(),
         expiresAt: timestamp("expires_at").notNull(),
         usedAt: timestamp("used_at"),
         createdAt: timestamp("created_at").defaultNow().notNull()
@@ -99,7 +110,7 @@ export function createAuthSchema(usersSchemaName = "rebase") {
      * App config - key/value store for custom settings
      */
     const appConfig = tableCreator("app_config", {
-        key: varchar("key", { length: 100 }).primaryKey(),
+        key: text("key").primaryKey(),
         value: jsonb("value").notNull(),
         updatedAt: timestamp("updated_at").defaultNow().notNull()
     });
@@ -110,8 +121,8 @@ export function createAuthSchema(usersSchemaName = "rebase") {
     const userIdentities = tableCreator("user_identities", {
         id: uuid("id").defaultRandom().primaryKey(),
         uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
-        provider: varchar("provider", { length: 50 }).notNull(), // e.g. 'google', 'linkedin'
-        providerId: varchar("provider_id", { length: 255 }).notNull(),
+        provider: text("provider").notNull(), // e.g. 'google', 'linkedin'
+        providerId: text("provider_id").notNull(),
         profileData: jsonb("profile_data"),
         createdAt: timestamp("created_at").defaultNow().notNull(),
         updatedAt: timestamp("updated_at").defaultNow().notNull()
@@ -125,9 +136,9 @@ export function createAuthSchema(usersSchemaName = "rebase") {
     const mfaFactors = tableCreator("mfa_factors", {
         id: uuid("id").defaultRandom().primaryKey(),
         uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
-        factorType: varchar("factor_type", { length: 20 }).notNull(), // 'totp'
-        secretEncrypted: varchar("secret_encrypted", { length: 500 }).notNull(),
-        friendlyName: varchar("friendly_name", { length: 255 }),
+        factorType: text("factor_type").notNull(), // 'totp'
+        secretEncrypted: text("secret_encrypted").notNull(),
+        friendlyName: text("friendly_name"),
         verified: boolean("verified").default(false).notNull(),
         createdAt: timestamp("created_at").defaultNow().notNull(),
         updatedAt: timestamp("updated_at").defaultNow().notNull()
@@ -141,7 +152,7 @@ export function createAuthSchema(usersSchemaName = "rebase") {
         factorId: uuid("factor_id").notNull().references(() => mfaFactors.id, { onDelete: "cascade" }),
         createdAt: timestamp("created_at").defaultNow().notNull(),
         verifiedAt: timestamp("verified_at"),
-        ipAddress: varchar("ip_address", { length: 45 }),
+        ipAddress: text("ip_address"),
         expiresAt: timestamp("expires_at").notNull()
     });
 
@@ -151,7 +162,7 @@ export function createAuthSchema(usersSchemaName = "rebase") {
     const recoveryCodes = tableCreator("recovery_codes", {
         id: uuid("id").defaultRandom().primaryKey(),
         uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
-        codeHash: varchar("code_hash", { length: 255 }).notNull(),
+        codeHash: text("code_hash").notNull(),
         usedAt: timestamp("used_at"),
         createdAt: timestamp("created_at").defaultNow().notNull()
     });
@@ -162,7 +173,7 @@ export function createAuthSchema(usersSchemaName = "rebase") {
     const magicLinkTokens = tableCreator("magic_link_tokens", {
         id: uuid("id").defaultRandom().primaryKey(),
         uid: uuid("uid").notNull().references(() => users.id, { onDelete: "cascade" }),
-        tokenHash: varchar("token_hash", { length: 255 }).notNull().unique(),
+        tokenHash: text("token_hash").notNull().unique(),
         expiresAt: timestamp("expires_at").notNull(),
         usedAt: timestamp("used_at"),
         createdAt: timestamp("created_at").defaultNow().notNull()

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

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

@@ -30,7 +30,9 @@ import { getTableName } from "@rebasepro/common";
 import {
     getSqlColumnType,
     resolveColumnName,
-    isIdProperty
+    isIdProperty,
+    planRelationalColumns,
+    planJunctionTables
 } from "./generate-postgres-ddl-logic";
 
 /**
@@ -62,10 +64,18 @@ export interface ExistingSchema {
     tables: Map<string, Set<string>>;
     /** `schema.typename` of every enum type that already exists. */
     enums: Set<string>;
+    /**
+     * `schema.table.constraint` of every constraint that already exists.
+     *
+     * Optional so a caller that only cares about tables can still build one by
+     * hand; absent is read as "none known", which at worst re-attempts a
+     * constraint that then fails harmlessly as a duplicate.
+     */
+    constraints?: Set<string>;
 }
 
 export interface EnsureAction {
-    kind: "create-enum" | "create-table" | "add-column";
+    kind: "create-enum" | "create-table" | "add-column" | "add-constraint";
     /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
     target: string;
     sql: string;
@@ -77,6 +87,18 @@ export interface EnsurePlan {
     statements: string[];
 }
 
+export interface EnsureOutcome extends EnsurePlan {
+    /**
+     * Constraints that could not be added — always non-fatal.
+     *
+     * A foreign key can only fail on data that already violates it, and the
+     * column it would police exists either way, so the collection still serves.
+     * Refusing to boot over one would turn a pre-existing data problem into an
+     * outage. Reported loudly instead.
+     */
+    failures: { target: string; error: string }[];
+}
+
 function schemaOf(collection: CollectionConfig): string {
     return isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
 }
@@ -183,34 +205,98 @@ export function planCollectionSchemaEnsure(
         });
     }
 
+    // 2b. Junction tables behind many-to-many relations. No collection declares
+    //     them, so the walk above never sees them — and until they existed, an
+    //     m2m write had nowhere to land and the junction's derived RLS had
+    //     nothing to attach to.
+    const junctions = planJunctionTables(collections);
+    for (const junction of junctions) {
+        const key = `${junction.schema}.${junction.table}`;
+        if (existing.tables.has(key) || created.has(key)) continue;
+        created.add(key);
+        actions.push({ kind: "create-table", target: key, sql: junction.createTable });
+    }
+
     // 3. Missing columns, on both brand-new and pre-existing tables.
+    const addColumn = (
+        key: string,
+        schema: string,
+        table: string,
+        column: string,
+        type: string
+    ): void => {
+        const present = existing.tables.get(key);
+        if (present?.has(column)) return;
+        actions.push({
+            kind: "add-column",
+            target: `${key}.${column}`,
+            // Never NOT NULL: an existing table with rows cannot take a
+            // non-null column without a default, and inventing one would be
+            // guessing at the customer's data.
+            sql: `ALTER TABLE "${schema}"."${table}" ADD COLUMN IF NOT EXISTS "${column}" ${type};`
+        });
+    };
+
     for (const collection of collections) {
         const key = qualified(collection);
         const schema = schemaOf(collection);
         const table = getTableName(collection);
-        const present = existing.tables.get(key) ?? new Set<string>();
         for (const [propName, prop] of Object.entries(collection.properties ?? {})) {
             const p = prop as Property;
             if (isIdProperty(propName, p, collection)) continue;
-            // A relation's own column is emitted by the DDL generator with a
-            // foreign key; adding a bare column here would create the column
-            // without the constraint and make the generator's later output
-            // disagree with the database. Left to a real migration.
+            // Relation and reference columns are planned from the shared
+            // relational planner below, which derives the column name, type and
+            // foreign key the same way `db push` does. Deriving them here as
+            // plain columns is what once produced a column with no constraint.
             if (p.type === "reference" || p.type === "relation") continue;
-            const column = resolveColumnName(propName, p);
-            if (present.has(column)) continue;
-            const type = getSqlColumnType(propName, p, collection, collections);
-            actions.push({
-                kind: "add-column",
-                target: `${key}.${column}`,
-                // Never NOT NULL: an existing table with rows cannot take a
-                // non-null column without a default, and inventing one would be
-                // guessing at the customer's data.
-                sql: `ALTER TABLE "${schema}"."${table}" ADD COLUMN IF NOT EXISTS "${column}" ${type};`
-            });
+            addColumn(key, schema, table, resolveColumnName(propName, p), getSqlColumnType(propName, p, collection, collections));
+        }
+    }
+
+    // 3b. A junction that already existed, but is short a column. One created
+    //     above already carries both — unlike a collection table, whose CREATE
+    //     declares only the identity column — so re-listing them would log two
+    //     no-op statements and inflate the count of changes applied.
+    for (const junction of junctions) {
+        const key = `${junction.schema}.${junction.table}`;
+        if (created.has(key)) continue;
+        for (const column of junction.columns) {
+            addColumn(key, junction.schema, junction.table, column.name, column.type);
         }
     }
 
+    // 3c. The columns relation and reference properties own.
+    for (const relational of planRelationalColumns(collections)) {
+        addColumn(
+            `${relational.schema}.${relational.table}`,
+            relational.schema,
+            relational.table,
+            relational.column,
+            relational.type
+        );
+    }
+
+    // 4. Foreign keys, last: the tables and columns on both ends have to exist
+    //    first, and a constraint is the one thing here that can fail on data
+    //    rather than on schema, so nothing else depends on it.
+    const knownConstraints = existing.constraints ?? new Set<string>();
+    const plannedConstraints = new Set<string>();
+    const foreignKeys = [
+        ...planRelationalColumns(collections).map(r => r.foreignKey),
+        ...junctions.flatMap(j => j.foreignKeys)
+    ];
+    for (const fk of foreignKeys) {
+        if (!fk) continue;
+        const name = `${fk.schema}.${fk.table}.${fk.constraintName}`;
+        if (knownConstraints.has(name) || plannedConstraints.has(name)) continue;
+        plannedConstraints.add(name);
+        actions.push({
+            kind: "add-constraint",
+            target: `${fk.schema}.${fk.table}.${fk.constraintName}`,
+            sql: fk.sql
+        });
+    }
+
     return { actions, statements: actions.map(a => a.sql) };
 }
 
@@ -250,7 +336,23 @@ export async function readExistingSchema(
     );
     for (const row of enumRows) enums.add(`${row.schema}.${row.name}`);
 
-    return { tables, enums };
+    // `ADD CONSTRAINT` has no IF NOT EXISTS, so an existing foreign key is
+    // skipped by name rather than guarded in SQL.
+    const constraints = new Set<string>();
+    const { rows: constraintRows } = await client.query<{
+        schema: string;
+        table: string;
+        name: string;
+    }>(
+        `SELECT n.nspname AS schema, c.relname AS table, con.conname AS name
+         FROM pg_constraint con
+         JOIN pg_class c ON con.conrelid = c.oid
+         JOIN pg_namespace n ON c.relnamespace = n.oid
+         WHERE n.nspname IN (${inList})`
+    );
+    for (const row of constraintRows) constraints.add(`${row.schema}.${row.table}.${row.name}`);
+
+    return { tables, enums, constraints };
 }
 
 /**
@@ -265,8 +367,14 @@ export async function ensureCollectionTables(
     client: Queryable,
     collections: CollectionConfig[],
     log?: (message: string) => void
-): Promise<EnsurePlan> {
-    const schemas = Array.from(new Set(collections.map(schemaOf)));
+): Promise<EnsureOutcome> {
+    // Junctions live alongside the collections that declare them, so their
+    // schema has to be read too — otherwise an existing junction reads as
+    // missing and its constraints as unplanned.
+    const schemas = Array.from(new Set([
+        ...collections.map(schemaOf),
+        ...planJunctionTables(collections).map(j => j.schema)
+    ]));
     for (const schema of schemas) {
         assertSafeIdentifier(schema, "schema name");
         if (schema !== "public") {
@@ -276,10 +384,11 @@ export async function ensureCollectionTables(
 
     const existing = await readExistingSchema(client, schemas);
     const plan = planCollectionSchemaEnsure(collections, existing);
+    const failures: { target: string; error: string }[] = [];
 
     if (plan.actions.length === 0) {
         log?.("Schema is up to date; nothing to create.");
-        return plan;
+        return { ...plan, failures };
     }
 
     for (const action of plan.actions) {
@@ -287,11 +396,19 @@ export async function ensureCollectionTables(
             await client.query(action.sql);
             log?.(`${action.kind}: ${action.target}`);
         } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // A foreign key is the only action that can fail on the customer's
+            // data rather than on the schema. The column it polices is already
+            // there, so the collection serves either way — record it and carry
+            // on rather than crash-looping the deployment.
+            if (action.kind === "add-constraint") {
+                failures.push({ target: action.target, error: message });
+                continue;
+            }
             throw new Error(
-                `Failed to ${action.kind} ${action.target}: ` +
-                `${err instanceof Error ? err.message : String(err)}\n  ${action.sql}`
+                `Failed to ${action.kind} ${action.target}: ${message}\n  ${action.sql}`
             );
         }
     }
-    return plan;
+    return { ...plan, failures };
 }