@rebasepro/server-postgres 0.10.1-canary.a54c057 → 0.10.1-canary.af2af91

package/src/schema/auth-schema.ts

@@ -1,4 +1,4 @@
-import { pgSchema, pgTable, varchar, uuid, timestamp, boolean, jsonb, text, unique } from "drizzle-orm/pg-core";
+import { pgSchema, pgTable, varchar, uuid, timestamp, boolean, jsonb, text, unique, index } from "drizzle-orm/pg-core";
 import { relations } from "drizzle-orm";
 
 /**
@@ -25,24 +25,62 @@ export function createAuthSchema(usersSchemaName = "rebase") {
         isAnonymous: boolean("is_anonymous").default(false).notNull(),
         roles: text("roles").array().default([]).notNull(),
         metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}).notNull(),
+        /**
+         * Sessions that began before this instant are dead, whatever tokens
+         * they still hold. Password resets and admin revocations stamp it.
+         *
+         * Deleting the user's refresh-token rows (which we also do) is not
+         * sufficient on its own: a request already in flight can insert a
+         * freshly rotated row microseconds after the delete and survive it.
+         * This timestamp cannot be outrun that way — it is checked against
+         * `refresh_tokens.session_started_at`, which rotation carries forward.
+         */
+        tokensValidAfter: timestamp("tokens_valid_after"),
         createdAt: timestamp("created_at").defaultNow().notNull(),
         updatedAt: timestamp("updated_at").defaultNow().notNull()
     });
 
 
     /**
-     * Refresh tokens for long-lived sessions
+     * Refresh tokens for long-lived sessions.
+     *
+     * A row is one token, not one device. Every token minted from the same
+     * sign-in shares a `sessionId`, and rotation ADDS a row rather than
+     * replacing one: the superseded token stays on file, flagged `revoked`
+     * with a `rotatedAt` stamp. That record is what lets the refresh endpoint
+     * tell a client replaying a token it never got an answer for (a response
+     * lost to a redeploy, a second tab racing on boot) apart from a stranger
+     * presenting a token that was never issued. Deleting the old row on sight
+     * — the previous behaviour — made those two cases indistinguishable, and
+     * the legitimate one is overwhelmingly the common one.
+     *
+     * There is deliberately NO unique constraint on (uid, user_agent,
+     * ip_address). Keying a session on the IP meant one row per "device",
+     * so a second browser profile behind the same NAT silently evicted the
+     * first, and a phone changing networks orphaned a row on every hop.
+     * User agent and IP are descriptive metadata for the sessions list;
+     * `sessionId` is the identity.
      */
     const refreshTokens = tableCreator("refresh_tokens", {
         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(),
         expiresAt: timestamp("expires_at").notNull(),
+        revoked: boolean("revoked").default(false).notNull(),
+        rotatedAt: timestamp("rotated_at"),
+        /**
+         * When the sign-in this token descends from happened — carried across
+         * every rotation, unlike `createdAt`. `users.tokensValidAfter` is
+         * compared against this, so a revocation cannot be outrun by a token
+         * that rotates immediately after it.
+         */
+        sessionStartedAt: timestamp("session_started_at").defaultNow().notNull(),
         userAgent: varchar("user_agent", { length: 500 }),
         ipAddress: varchar("ip_address", { length: 45 }),
         createdAt: timestamp("created_at").defaultNow().notNull()
     }, (table) => ({
-        uniqueDeviceSession: unique("unique_device_session").on(table.uid, table.userAgent, table.ipAddress)
+        sessionIdx: index("idx_refresh_tokens_session").on(table.sessionId)
     }));
 
     /**

package/src/schema/destructive-sql.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure helpers that classify an Atlas declarative-apply plan as destructive
+ * or not, and decide what `rebase db push` should do about it.
+ *
+ * `db push` runs `atlas schema apply` to make the live database match the
+ * generated `schema.sql`. Removing a collection field compiles to
+ * `DROP COLUMN`; renaming compiles to drop-then-add — either destroys data.
+ * We first run the apply with `--dry-run` to obtain the planned SQL, scan it
+ * here, and refuse to auto-approve anything destructive without an explicit
+ * opt-in.
+ *
+ * Everything in this file is side-effect free so it can be unit-tested
+ * without Atlas or a database.
+ */
+
+/**
+ * SQL fragments that destroy data or data-bearing objects. Matched
+ * case-insensitively against each statement of the plan. `IF EXISTS` /
+ * whitespace variations are tolerated by the regexes below.
+ */
+const DESTRUCTIVE_PATTERNS: { label: string; re: RegExp }[] = [
+    { label: "DROP TABLE", re: /\bDROP\s+TABLE\b/i },
+    { label: "DROP COLUMN", re: /\bDROP\s+COLUMN\b/i },
+    { label: "DROP SCHEMA", re: /\bDROP\s+SCHEMA\b/i },
+    { label: "DROP VIEW", re: /\bDROP\s+(MATERIALIZED\s+)?VIEW\b/i },
+    { label: "DROP TYPE", re: /\bDROP\s+TYPE\b/i },
+    { label: "TRUNCATE", re: /\bTRUNCATE\b/i }
+];
+
+/**
+ * Split a SQL script into individual statements, dropping blank lines and
+ * `--` comment lines. Deliberately simple: Atlas emits one plain statement
+ * per `;`, without string literals that contain semicolons in a schema DDL
+ * plan, so a naive split is safe and keeps this dependency-free.
+ */
+export function splitSqlStatements(sql: string): string[] {
+    // Strip full-line SQL comments so a commented-out DROP never trips the
+    // detector, then split on semicolons.
+    const withoutComments = sql
+        .split("\n")
+        .filter((line) => !line.trim().startsWith("--"))
+        .join("\n");
+    return withoutComments
+        .split(";")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+
+export interface DestructiveStatement {
+    /** The offending statement (trimmed, without the trailing `;`). */
+    statement: string;
+    /** Which destructive operation it was flagged for, e.g. "DROP COLUMN". */
+    kind: string;
+}
+
+/**
+ * Scan an Atlas plan (the SQL printed by `schema apply --dry-run`) and return
+ * the statements that would destroy data. An empty array means the plan is
+ * safe to auto-approve.
+ */
+export function detectDestructiveStatements(planSql: string): DestructiveStatement[] {
+    const found: DestructiveStatement[] = [];
+    for (const statement of splitSqlStatements(planSql)) {
+        for (const { label, re } of DESTRUCTIVE_PATTERNS) {
+            if (re.test(statement)) {
+                found.push({ statement, kind: label });
+                break; // one label per statement is enough to flag it
+            }
+        }
+    }
+    return found;
+}
+
+export type PushDecision = "apply" | "confirm" | "refuse";
+
+/**
+ * Decide how `db push` should proceed given the plan's destructiveness and
+ * the invocation context.
+ *
+ *  - No destructive statements → `apply` (safe to auto-approve).
+ *  - Destructive + `--allow-destructive` → `apply` (operator opted in).
+ *  - Destructive + interactive TTY → `confirm` (prompt before applying).
+ *  - Destructive + non-interactive → `refuse` (never silently drop data in
+ *    CI / scripts / agents).
+ */
+export function decidePushSafety(opts: {
+    destructiveCount: number;
+    allowDestructive: boolean;
+    interactive: boolean;
+}): PushDecision {
+    if (opts.destructiveCount === 0) return "apply";
+    if (opts.allowDestructive) return "apply";
+    return opts.interactive ? "confirm" : "refuse";
+}

package/src/schema/doctor.ts

@@ -62,12 +62,10 @@ export function getExpectedColumnType(prop: Property): string | null {
             if (sp.enum) return "USER-DEFINED"; // pgEnum → USER-DEFINED in information_schema
             if ("isId" in sp && sp.isId === "uuid") return "uuid";
             if (sp.columnType === "uuid") return "uuid";
-            // A markdown/multiline string compiles to `text`, not varchar — the
-            // generator treats those UI hints as column-type signals, so the
-            // expectation here must too or every such column reads as drift.
-            if (sp.columnType === "text" || sp.ui?.markdown || sp.ui?.multiline) return "text";
             if (sp.columnType === "char") return "character";
-            return "character varying";
+            if (sp.columnType === "varchar") return "character varying";
+            // `text` is the default — see generate-postgres-ddl-logic.
+            return "text";
         }
         case "number": {
             const np = prop as NumberProperty;
@@ -122,7 +120,9 @@ export function getExpectedColumnType(prop: Property): string | null {
         case "relation":
             return null; // FK columns are derived from the relation, not from the property
         case "reference":
-            return "character varying"; // References default to varchar FK
+            // A reference FK follows the key it points at, and a string key is
+            // `text` — see generate-postgres-ddl-logic.
+            return "text";
         case "vector":
             return "USER-DEFINED";
         case "binary":

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

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "@jest/globals";
+import type { CollectionConfig } from "@rebasepro/types";
+import {
+    planCollectionSchemaEnsure,
+    ensureCollectionTables,
+    type ExistingSchema,
+    type Queryable
+} from "./ensure-collection-tables";
+
+const posts = {
+    name: "Posts",
+    slug: "posts",
+    properties: {
+        id: { name: "ID", type: "string", isId: "uuid" },
+        title: { name: "Title", type: "string" },
+        views: { name: "Views", type: "number" },
+        status: {
+            name: "Status",
+            type: "string",
+            enum: [
+                { id: "draft", label: "Draft" },
+                { id: "published", label: "Published" }
+            ]
+        }
+    }
+} as unknown as CollectionConfig;
+
+const empty = (): ExistingSchema => ({ tables: new Map(), enums: new Set() });
+
+const withTable = (key: string, columns: string[]): ExistingSchema => ({
+    tables: new Map([[key, new Set(columns)]]),
+    enums: new Set()
+});
+
+describe("planning an additive schema ensure", () => {
+    it("creates a missing table, its enum type, and its columns in that order", () => {
+        const plan = planCollectionSchemaEnsure([posts], empty());
+        const kinds = plan.actions.map(a => a.kind);
+
+        // The enum must exist before the column that references it, and the
+        // table before its own columns.
+        expect(kinds.indexOf("create-enum")).toBeLessThan(kinds.indexOf("create-table"));
+        expect(kinds.indexOf("create-table")).toBeLessThan(kinds.indexOf("add-column"));
+        expect(plan.statements.join("\n")).toMatch(/CREATE TABLE IF NOT EXISTS "public"\."posts"/);
+    });
+
+    it("adds only the columns an existing table is missing", () => {
+        const plan = planCollectionSchemaEnsure([posts], withTable("public.posts", ["id", "title"]));
+        const added = plan.actions.filter(a => a.kind === "add-column").map(a => a.target);
+
+        expect(added).toContain("public.posts.views");
+        expect(added).toContain("public.posts.status");
+        expect(added).not.toContain("public.posts.title");
+        expect(plan.actions.some(a => a.kind === "create-table")).toBe(false);
+    });
+
+    it("is a no-op against a database that is already current", () => {
+        const existing: ExistingSchema = {
+            tables: new Map([["public.posts", new Set(["id", "title", "views", "status"])]]),
+            enums: new Set(["public.posts_status"])
+        };
+        expect(planCollectionSchemaEnsure([posts], existing).actions).toEqual([]);
+    });
+
+    it("skips an enum type that already exists, since CREATE TYPE has no IF NOT EXISTS", () => {
+        const existing: ExistingSchema = { tables: new Map(), enums: new Set(["public.posts_status"]) };
+        const plan = planCollectionSchemaEnsure([posts], existing);
+        expect(plan.actions.some(a => a.kind === "create-enum")).toBe(false);
+    });
+
+    it("NEVER emits a destructive statement, whatever the database contains", () => {
+        // The core safety property. This runs unattended against customer data
+        // with nobody reading a diff, so a column the collections no longer
+        // mention must be left alone, not dropped.
+        const existing = withTable("public.posts", ["id", "title", "legacy_column", "another_old_one"]);
+        const sql = planCollectionSchemaEnsure([posts], existing).statements.join("\n");
+
+        expect(sql).not.toMatch(/\bDROP\b/i);
+        expect(sql).not.toMatch(/\bTRUNCATE\b/i);
+        expect(sql).not.toMatch(/ALTER COLUMN/i);
+        expect(sql).not.toMatch(/legacy_column/);
+    });
+
+    it("never adds a NOT NULL column, which an existing table with rows could not take", () => {
+        const sql = planCollectionSchemaEnsure([posts], withTable("public.posts", ["id"]))
+            .statements.join("\n");
+        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 }
+            }
+        } as unknown as CollectionConfig;
+        const plan = planCollectionSchemaEnsure([withRelation], withTable("public.posts", ["id"]));
+        expect(plan.actions.some(a => a.target.endsWith(".author"))).toBe(false);
+    });
+});
+
+describe("applying the plan", () => {
+    function fakeClient(): { client: Queryable; executed: string[] } {
+        const executed: string[] = [];
+        const client: Queryable = {
+            async query<T>(sql: string): Promise<{ rows: T[] }> {
+                executed.push(sql);
+                return { rows: [] as T[] };
+            }
+        };
+        return { client, executed };
+    }
+
+    it("creates the schema, reads what exists, then applies", async () => {
+        const { client, executed } = fakeClient();
+        const plan = await ensureCollectionTables(client, [posts]);
+
+        expect(plan.actions.length).toBeGreaterThan(0);
+        expect(executed.some(s => s.includes("information_schema.columns"))).toBe(true);
+        expect(executed.some(s => s.includes("CREATE TABLE IF NOT EXISTS"))).toBe(true);
+    });
+
+    it("surfaces which statement failed rather than a bare driver error", async () => {
+        const client: Queryable = {
+            async query<T>(sql: string): Promise<{ rows: T[] }> {
+                if (sql.startsWith("CREATE TABLE")) throw new Error("permission denied");
+                return { rows: [] as T[] };
+            }
+        };
+        await expect(ensureCollectionTables(client, [posts])).rejects.toThrow(/permission denied/);
+        await expect(ensureCollectionTables(client, [posts])).rejects.toThrow(/public\.posts/);
+    });
+
+    it("does nothing when the database is already current", async () => {
+        const client: Queryable = {
+            async query<T>(sql: string): Promise<{ rows: T[] }> {
+                if (sql.includes("information_schema.columns")) {
+                    return {
+                        rows: ["id", "title", "views", "status"].map(c => ({
+                            table_schema: "public",
+                            table_name: "posts",
+                            column_name: c
+                        })) as unknown as T[]
+                    };
+                }
+                if (sql.includes("pg_type")) {
+                    return { rows: [{ schema: "public", name: "posts_status" }] as unknown as T[] };
+                }
+                return { rows: [] as T[] };
+            }
+        };
+        const plan = await ensureCollectionTables(client, [posts]);
+        expect(plan.actions).toEqual([]);
+    });
+});

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

@@ -0,0 +1,297 @@
+/**
+ * Bringing a database up to date with a bundle's collections, additively.
+ *
+ * ## Why this exists
+ *
+ * A managed runtime boots someone else's compiled project against a database it
+ * has never seen. Auth tables are ensured at boot already, but collection tables
+ * were not created by anything: the platform ran the app and every `/api/data/*`
+ * request answered 500 on a missing relation. `rebase db push` cannot help — it
+ * is an Atlas-driven CLI command, and the runtime image ships no CLI.
+ *
+ * ## Why additive-only, forever
+ *
+ * This runs unattended, against a database with customers' data in it, with no
+ * human reading a diff. So it may only ever do things that cannot lose data:
+ * create a missing table, add a missing column, create a missing enum type.
+ *
+ * It will **never** drop a table or a column, narrow a type, or alter a
+ * constraint. A removed field leaves its column behind; a renamed field looks
+ * like an addition and the old column stays. That is the correct trade for an
+ * automated path — the alternative is an unattended process that can silently
+ * destroy a column, which is precisely the failure `db push` was hardened
+ * against. Destructive changes stay a deliberate, human-reviewed migration.
+ *
+ * Because of that, this is safe to run on every boot, and re-running it is a
+ * no-op.
+ */
+import { type CollectionConfig, type Property, isPostgresCollectionConfig } from "@rebasepro/types";
+import { getTableName } from "@rebasepro/common";
+import {
+    getSqlColumnType,
+    resolveColumnName,
+    isIdProperty
+} from "./generate-postgres-ddl-logic";
+
+/**
+ * The subset of a database handle this needs: run a statement, get rows back.
+ *
+ * Deliberately parameterless. Everything here is DDL or catalogue reads keyed by
+ * schema name, and schema names are identifiers — they cannot be bound as
+ * parameters anyway. They are validated against {@link SAFE_IDENTIFIER} before
+ * they reach a statement, so a config that somehow carried a quote is refused
+ * rather than concatenated.
+ */
+export interface Queryable {
+    query<T = unknown>(sql: string): Promise<{ rows: T[] }>;
+}
+
+/** Postgres identifiers this module is willing to interpolate. */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+function assertSafeIdentifier(value: string, what: string): string {
+    if (!SAFE_IDENTIFIER.test(value)) {
+        throw new Error(`Refusing to build SQL with an unsafe ${what}: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+
+/** What the database currently has, as the planner needs it. */
+export interface ExistingSchema {
+    /** `schema.table` → set of column names. */
+    tables: Map<string, Set<string>>;
+    /** `schema.typename` of every enum type that already exists. */
+    enums: Set<string>;
+}
+
+export interface EnsureAction {
+    kind: "create-enum" | "create-table" | "add-column";
+    /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
+    target: string;
+    sql: string;
+}
+
+export interface EnsurePlan {
+    actions: EnsureAction[];
+    /** Every statement, in dependency order. Empty when the schema is current. */
+    statements: string[];
+}
+
+function schemaOf(collection: CollectionConfig): string {
+    return isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
+}
+
+function qualified(collection: CollectionConfig): string {
+    return `${schemaOf(collection)}.${getTableName(collection)}`;
+}
+
+/**
+ * Enum types a collection's properties require, as `schema.typename`.
+ *
+ * Named exactly as the DDL generator names them (`<table>_<column>`), because
+ * a column added here has to reference the same type the generator would have
+ * created — a second, differently-named type for the same field would be a
+ * silent schema fork.
+ */
+function requiredEnums(collection: CollectionConfig): { name: string; values: string[] }[] {
+    const table = getTableName(collection);
+    const schema = schemaOf(collection);
+    const out: { name: string; values: string[] }[] = [];
+    for (const [propName, prop] of Object.entries(collection.properties ?? {})) {
+        const p = prop as Property;
+        if (!("enum" in p) || !p.enum) continue;
+        if (p.type !== "string" && p.type !== "number") continue;
+        const values = (p.enum as unknown[])
+            .map(entry =>
+                entry && typeof entry === "object" && "id" in (entry as Record<string, unknown>)
+                    ? String((entry as Record<string, unknown>).id)
+                    : String(entry)
+            )
+            .filter(v => v.length > 0);
+        if (values.length === 0) continue;
+        out.push({ name: `${schema}.${table}_${resolveColumnName(propName, p)}`, values });
+    }
+    return out;
+}
+
+/** Single-quote escaping for an enum label. */
+function quoteLiteral(value: string): string {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+
+/**
+ * Decide what to add. Pure — the caller supplies what exists and runs the result.
+ *
+ * Ordering matters and is deliberate: enum types before the tables and columns
+ * that reference them, tables before the columns added to other tables (a new
+ * table may be the target of a relation), and nothing is emitted twice.
+ */
+export function planCollectionSchemaEnsure(
+    collections: CollectionConfig[],
+    existing: ExistingSchema
+): EnsurePlan {
+    const actions: EnsureAction[] = [];
+    const plannedEnums = new Set<string>();
+
+    // 1. Enum types. `CREATE TYPE` has no IF NOT EXISTS, so an existing type is
+    //    skipped by name rather than guarded in SQL.
+    for (const collection of collections) {
+        for (const { name, values } of requiredEnums(collection)) {
+            if (existing.enums.has(name) || plannedEnums.has(name)) continue;
+            plannedEnums.add(name);
+            const [schema, typeName] = name.split(".");
+            actions.push({
+                kind: "create-enum",
+                target: name,
+                sql: `CREATE TYPE "${schema}"."${typeName}" AS ENUM (${values.map(quoteLiteral).join(", ")});`
+            });
+        }
+    }
+
+    // 2. Missing tables. Only the identity column is created here; every other
+    //    column is added by step 3, so a new table and an existing table that
+    //    gained a field travel the exact same code path. One way to build a
+    //    column means one way for it to be wrong.
+    const created = new Set<string>();
+    for (const collection of collections) {
+        const key = qualified(collection);
+        if (existing.tables.has(key) || created.has(key)) continue;
+        created.add(key);
+        const schema = schemaOf(collection);
+        const table = getTableName(collection);
+        const idEntry = Object.entries(collection.properties ?? {}).find(([n, p]) =>
+            isIdProperty(n, p as Property, collection)
+        );
+        const idName = idEntry ? resolveColumnName(idEntry[0], idEntry[1] as Property) : "id";
+        const idProp = idEntry?.[1] as Property | undefined;
+        let idDef: string;
+        if (idProp?.type === "number") {
+            idDef = `"${idName}" BIGSERIAL PRIMARY KEY`;
+        } else if (
+            idProp &&
+            idProp.type === "string" &&
+            (idProp as { isId?: unknown }).isId === "uuid"
+        ) {
+            idDef = `"${idName}" UUID PRIMARY KEY DEFAULT gen_random_uuid()`;
+        } else {
+            idDef = `"${idName}" TEXT PRIMARY KEY`;
+        }
+        actions.push({
+            kind: "create-table",
+            target: key,
+            sql: `CREATE TABLE IF NOT EXISTS "${schema}"."${table}" (${idDef});`
+        });
+    }
+
+    // 3. Missing columns, on both brand-new and pre-existing tables.
+    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.
+            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};`
+            });
+        }
+    }
+
+    return { actions, statements: actions.map(a => a.sql) };
+}
+
+/** Read what the database has, for the schemas the collections live in. */
+export async function readExistingSchema(
+    client: Queryable,
+    schemas: string[]
+): Promise<ExistingSchema> {
+    const tables = new Map<string, Set<string>>();
+    const enums = new Set<string>();
+    if (schemas.length === 0) return { tables, enums };
+
+    const inList = schemas
+        .map(schema => `'${assertSafeIdentifier(schema, "schema name")}'`)
+        .join(", ");
+
+    const { rows: columns } = await client.query<{
+        table_schema: string;
+        table_name: string;
+        column_name: string;
+    }>(
+        `SELECT table_schema, table_name, column_name
+         FROM information_schema.columns
+         WHERE table_schema IN (${inList})`
+    );
+    for (const row of columns) {
+        const key = `${row.table_schema}.${row.table_name}`;
+        if (!tables.has(key)) tables.set(key, new Set());
+        tables.get(key)!.add(row.column_name);
+    }
+
+    const { rows: enumRows } = await client.query<{ schema: string; name: string }>(
+        `SELECT n.nspname AS schema, t.typname AS name
+         FROM pg_type t
+         JOIN pg_namespace n ON t.typnamespace = n.oid
+         WHERE t.typtype = 'e' AND n.nspname IN (${inList})`
+    );
+    for (const row of enumRows) enums.add(`${row.schema}.${row.name}`);
+
+    return { tables, enums };
+}
+
+/**
+ * Bring the database up to date. Returns what it did.
+ *
+ * Each statement runs on its own rather than in one transaction: they are all
+ * independently safe and idempotent, and a single failure (an enum label that
+ * cannot be added, say) should not roll back the tables that were created fine.
+ * The error is surfaced with the statement that caused it.
+ */
+export async function ensureCollectionTables(
+    client: Queryable,
+    collections: CollectionConfig[],
+    log?: (message: string) => void
+): Promise<EnsurePlan> {
+    const schemas = Array.from(new Set(collections.map(schemaOf)));
+    for (const schema of schemas) {
+        assertSafeIdentifier(schema, "schema name");
+        if (schema !== "public") {
+            await client.query(`CREATE SCHEMA IF NOT EXISTS "${schema}";`);
+        }
+    }
+
+    const existing = await readExistingSchema(client, schemas);
+    const plan = planCollectionSchemaEnsure(collections, existing);
+
+    if (plan.actions.length === 0) {
+        log?.("Schema is up to date; nothing to create.");
+        return plan;
+    }
+
+    for (const action of plan.actions) {
+        try {
+            await client.query(action.sql);
+            log?.(`${action.kind}: ${action.target}`);
+        } catch (err) {
+            throw new Error(
+                `Failed to ${action.kind} ${action.target}: ` +
+                `${err instanceof Error ? err.message : String(err)}\n  ${action.sql}`
+            );
+        }
+    }
+    return plan;
+}