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

package/src/schema/generate-postgres-ddl-logic.ts

@@ -1,6 +1,8 @@
 import { CollectionConfig, NumberProperty, Property, ResolvedRelation, RelationProperty, SecurityOperation, SecurityRule, StringProperty, isPostgresCollectionConfig, DateProperty, ArrayProperty, MapProperty, ReferenceProperty, VectorProperty, BinaryProperty, isManyToMany, type ResolvedManyToMany, type ResolvedBelongsTo } from "@rebasepro/types";
-import { getEnumVarName, getTableName, resolveCollectionRelations, findRelation, securityRuleToConditions, policyToPostgres, getEffectiveSecurityRules, getInjectedSecurityRules, resolveJunctionSpecs, getJunctionSecurityRules, getJunctionCollectionConfig } from "@rebasepro/common";
-import { toSnakeCase, getPolicyNamesForRule } from "@rebasepro/utils";
+import { getEnumVarName, getTableName, resolveCollectionRelations, findRelation, securityRuleToConditions, policyToPostgres, getEffectiveSecurityRules, getInjectedSecurityRules, resolveJunctionSpecs, getJunctionSecurityRules, getJunctionCollectionConfig, resolveStringColumnLength, relationalCollections } from "@rebasepro/common";
+import { toSnakeCase, getPolicyNamesForRule, generateForeignKeyName, legacyForeignKeyName } from "@rebasepro/utils";
+import { AUTH_USERS_COLUMNS, authUsersColumnDefinition, authUsersColumnSql, isAuthCollection } from "./auth-users-columns";
+import { REBASE_SCHEMA } from "@rebasepro/types";
 
 // --- Helper Functions ---
 
@@ -11,7 +13,7 @@ export const resolveColumnName = (propName: string, prop?: Property | null): str
     return toSnakeCase(propName);
 };
 
-const getPrimaryKeyProp = (collection: CollectionConfig): { name: string, type: "string" | "number", isUuid: boolean } => {
+export const getPrimaryKeyProp = (collection: CollectionConfig): { name: string, type: "string" | "number", isUuid: boolean } => {
     if (collection.properties) {
         const idPropEntry = Object.entries(collection.properties).find(([_, prop]) => "isId" in (prop as unknown as object) && Boolean((prop as unknown as Record<string, unknown>).isId));
         if (idPropEntry) {
@@ -28,14 +30,18 @@ const getPrimaryKeyProp = (collection: CollectionConfig): { name: string, type:
     return { name: "id", type: "string", isUuid: isUuid ?? false };
 };
 
-const isNumericId = (collection: CollectionConfig): boolean => {
+export const isNumericId = (collection: CollectionConfig): boolean => {
     return getPrimaryKeyProp(collection).type === "number";
 };
 
-const getPrimaryKeyName = (collection: CollectionConfig): string => {
+export const getPrimaryKeyName = (collection: CollectionConfig): string => {
     return getPrimaryKeyProp(collection).name;
 };
 
+/** The column type a junction holds for one endpoint's primary key. */
+const junctionKeyType = (collection: CollectionConfig): string =>
+    isNumericId(collection) ? "INTEGER" : (getPrimaryKeyProp(collection).isUuid ? "UUID" : "TEXT");
+
 export const isIdProperty = (propName: string, prop: Property, collection: CollectionConfig): boolean => {
     if ("isId" in prop && Boolean(prop.isId)) return true;
     const hasExplicitId = Object.values(collection.properties ?? {}).some(p => "isId" in (p as unknown as object) && Boolean((p as unknown as Record<string, unknown>).isId));
@@ -45,7 +51,28 @@ export const isIdProperty = (propName: string, prop: Property, collection: Colle
 
 type ResolveCollection = (slug: string) => CollectionConfig | undefined;
 
-const generatePolicyDdl = (collection: CollectionConfig, rule: SecurityRule, resolveCollection: ResolveCollection): string => {
+/**
+ * Render statements produced by {@link generatePolicyStatements} back into the
+ * exact string the DDL/policies files have always carried: each statement on
+ * its own line, terminated by a newline. Keeping the string form derived from
+ * the statement array means the two can never drift — the boot-time applier and
+ * the generated `policies.sql` emit the same SQL, from the same source.
+ */
+const statementsToDdl = (statements: string[]): string => statements.map(s => `${s}\n`).join("");
+
+const generatePolicyDdl = (collection: CollectionConfig, rule: SecurityRule, resolveCollection: ResolveCollection): string =>
+    statementsToDdl(generatePolicyStatements(collection, rule, resolveCollection));
+
+/**
+ * The individual SQL statements a single security rule compiles to: a
+ * `DROP POLICY IF EXISTS` / `CREATE POLICY` pair per operation, each a complete
+ * statement (terminated by `;`, no trailing newline).
+ *
+ * This is the primitive the boot-time RLS applier runs one statement at a time
+ * (the runtime's DB handle speaks the extended query protocol, which forbids
+ * multiple commands in one execute), while `db push` writes the joined string.
+ */
+export const generatePolicyStatements = (collection: CollectionConfig, rule: SecurityRule, resolveCollection: ResolveCollection): string[] => {
     const tableName = getTableName(collection);
     const ops: readonly SecurityOperation[] = rule.operations && rule.operations.length > 0
         ? rule.operations
@@ -53,12 +80,12 @@ const generatePolicyDdl = (collection: CollectionConfig, rule: SecurityRule, res
 
     const policyNames = getPolicyNamesForRule(rule, tableName);
 
-    return ops.map((op, opIdx) => {
-        return generateSinglePolicyDdl(collection, rule, op, policyNames[opIdx], resolveCollection);
-    }).join("");
+    return ops.flatMap((op, opIdx) => {
+        return generateSinglePolicyStatements(collection, rule, op, policyNames[opIdx], resolveCollection);
+    });
 };
 
-const generateSinglePolicyDdl = (collection: CollectionConfig, rule: SecurityRule, operation: SecurityOperation, policyName: string, resolveCollection: ResolveCollection): string => {
+const generateSinglePolicyStatements = (collection: CollectionConfig, rule: SecurityRule, operation: SecurityOperation, policyName: string, resolveCollection: ResolveCollection): string[] => {
     const schema = isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
     const tableName = getTableName(collection);
     const mode = (rule.mode ?? "permissive").toUpperCase();
@@ -83,13 +110,24 @@ const generateSinglePolicyDdl = (collection: CollectionConfig, rule: SecurityRul
         withCheckClause = "false";
     }
 
-    let ddl = `DROP POLICY IF EXISTS "${policyName}" ON "${schema}"."${tableName}";\n`;
-    ddl += `CREATE POLICY "${policyName}" ON "${schema}"."${tableName}" AS ${mode} FOR ${operationUpper} TO ${pgRoles.map(r => `"${r}"`).join(", ")}`;
-    if (usingClause) ddl += ` USING (${usingClause})`;
-    if (withCheckClause) ddl += ` WITH CHECK (${withCheckClause})`;
-    return `${ddl};\n`;
+    const drop = `DROP POLICY IF EXISTS "${policyName}" ON "${schema}"."${tableName}";`;
+    let create = `CREATE POLICY "${policyName}" ON "${schema}"."${tableName}" AS ${mode} FOR ${operationUpper} TO ${pgRoles.map(r => `"${r}"`).join(", ")}`;
+    if (usingClause) create += ` USING (${usingClause})`;
+    if (withCheckClause) create += ` WITH CHECK (${withCheckClause})`;
+    create += ";";
+    return [drop, create];
 };
 
+/**
+ * Single-quote escaping for a SQL string literal (PostgreSQL doubles the
+ * quote). Enum labels come straight from user-authored collection config, so a
+ * label like `it's` closes the literal early and the whole generated file stops
+ * parsing at the `CREATE TYPE`. Lives here rather than next to its other caller
+ * because ensure-collection-tables already imports from this module — the
+ * reverse would be a cycle.
+ */
+export const quoteSqlLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+
 export const getSqlColumnType = (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]): string => {
     switch (prop.type) {
         case "string": {
@@ -103,11 +141,15 @@ export const getSqlColumnType = (propName: string, prop: Property, collection: C
             if (stringProp.isId === "uuid" || stringProp.columnType === "uuid") {
                 return "UUID";
             }
+            // Width comes from `validation.max` when the property states one.
+            // It used to be a hardcoded 255 here and *absent* on the Drizzle
+            // path, so the same property produced a bounded column down one
+            // generator and an unbounded one down the other.
             if (stringProp.columnType === "char") {
-                return "CHAR(255)";
+                return `CHAR(${resolveStringColumnLength(stringProp)})`;
             }
             if (stringProp.columnType === "varchar") {
-                return "VARCHAR(255)";
+                return `VARCHAR(${resolveStringColumnLength(stringProp)})`;
             }
             // `text` is the default. The two generators disagreed here before:
             // this one emitted VARCHAR(255) while the drizzle path emitted a bare
@@ -196,14 +238,24 @@ export const getSqlColumnType = (propName: string, prop: Property, collection: C
 };
 
 export const generatePostgresDdl = async (
-    collections: CollectionConfig[],
+    allCollections: CollectionConfig[],
     options: { includePolicies?: boolean } = { includePolicies: true }
 ): Promise<string> => {
+    // Only the collections this engine stores. See `relationalCollections`.
+    const collections = relationalCollections(allCollections);
     let ddl = "-- This file is auto-generated by the Rebase DDL generator. Do not edit manually.\n\n";
 
-    // 1. Create custom schemas
+    // 1. Create custom schemas.
+    //
+    // `rebase` is unconditional and load-bearing. The RLS helper functions live
+    // in it, so the migration preamble creates it — which puts it in Atlas's
+    // replayed state, and anything in that state but absent from this desired
+    // schema gets a `DROP SCHEMA … CASCADE` planned against it. That would take
+    // the auth tables. It used to appear here only when some collection
+    // happened to declare `schema: "rebase"`; the scaffold's users collection
+    // does, which is why nobody hit it, but nothing guaranteed it.
     const uniqueSchemas = Array.from(new Set([
-        "auth",
+        REBASE_SCHEMA,
         ...collections.map(c => isPostgresCollectionConfig(c) ? c.schema : undefined).filter(Boolean)
     ]));
     uniqueSchemas.forEach(schema => {
@@ -212,6 +264,13 @@ export const generatePostgresDdl = async (
     if (uniqueSchemas.length > 0) ddl += "\n";
 
     // 2. Generate Enums
+    //
+    // The enum type name is derived from table + column, so two collections
+    // mapped onto the same table — or two properties whose `columnName`
+    // resolves to the same column — land on the same name. `CREATE TYPE` has no
+    // IF NOT EXISTS, so emitting it twice aborts the whole file on the second
+    // statement. Dedupe by name, matching planCollectionSchemaEnsure.
+    const emittedEnums = new Set<string>();
     collections.forEach(collection => {
         const collectionTable = getTableName(collection);
         const schema = isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
@@ -223,8 +282,9 @@ export const generatePostgresDdl = async (
                         String(typeof v === "object" && v !== null && "id" in v ? v.id : v)
                     )
                     : Object.keys(prop.enum);
-                if (values.length > 0) {
-                    ddl += `CREATE TYPE "${schema}"."${enumDbName}" AS ENUM (${values.map(v => `'${v}'`).join(", ")});\n`;
+                if (values.length > 0 && !emittedEnums.has(`${schema}.${enumDbName}`)) {
+                    emittedEnums.add(`${schema}.${enumDbName}`);
+                    ddl += `CREATE TYPE "${schema}"."${enumDbName}" AS ENUM (${values.map(quoteSqlLiteral).join(", ")});\n`;
                 }
             }
         });
@@ -307,8 +367,8 @@ export const generatePostgresDdl = async (
             ddl += `  PRIMARY KEY ("${sourceColumn}", "${targetColumn}")\n`;
             ddl += `);\n\n`;
 
-            fkStatements.push(`ALTER TABLE "${schema}"."${baseTableName}" ADD CONSTRAINT "${baseTableName}_${sourceColumn}_fkey" FOREIGN KEY ("${sourceColumn}") REFERENCES "${sourceSchema}"."${sourceTable}" ("${sourceId}") ON DELETE ${onDelete.toUpperCase()};`);
-            fkStatements.push(`ALTER TABLE "${schema}"."${baseTableName}" ADD CONSTRAINT "${baseTableName}_${targetColumn}_fkey" FOREIGN KEY ("${targetColumn}") REFERENCES "${targetSchema}"."${targetTable}" ("${targetId}") ON DELETE ${onDelete.toUpperCase()};`);
+            fkStatements.push(`ALTER TABLE "${schema}"."${baseTableName}" ADD CONSTRAINT "${toPostgresIdentifier(`${baseTableName}_${sourceColumn}_fkey`)}" FOREIGN KEY ("${sourceColumn}") REFERENCES "${sourceSchema}"."${sourceTable}" ("${sourceId}") ON DELETE ${onDelete.toUpperCase()};`);
+            fkStatements.push(`ALTER TABLE "${schema}"."${baseTableName}" ADD CONSTRAINT "${toPostgresIdentifier(`${baseTableName}_${targetColumn}_fkey`)}" FOREIGN KEY ("${targetColumn}") REFERENCES "${targetSchema}"."${targetTable}" ("${targetId}") ON DELETE ${onDelete.toUpperCase()};`);
 
             if (options.includePolicies) {
                 // Junction tables are generated tables like any other: locked by
@@ -366,7 +426,7 @@ export const generatePostgresDdl = async (
                     if (required) colDef += " NOT NULL";
                     columns.push(colDef);
 
-                    fkStatements.push(`ALTER TABLE "${schema}"."${baseTableName}" ADD CONSTRAINT "${baseTableName}_${relInfo.localKey}_fkey" FOREIGN KEY ("${relInfo.localKey}") REFERENCES "${targetSchema}"."${targetTable}" ("${targetId}") ON DELETE ${onDeleteVal.toUpperCase()}${onUpdate};`);
+                    fkStatements.push(`ALTER TABLE "${schema}"."${baseTableName}" ADD CONSTRAINT "${toPostgresIdentifier(`${baseTableName}_${relInfo.localKey}_fkey`)}" FOREIGN KEY ("${relInfo.localKey}") REFERENCES "${targetSchema}"."${targetTable}" ("${targetId}") ON DELETE ${onDeleteVal.toUpperCase()}${onUpdate};`);
                 } else if (prop.type === "reference") {
                     const refProp = prop as ReferenceProperty;
                     const targetCollection = collections.find(c => c.slug === refProp.path || getTableName(c) === refProp.path);
@@ -388,10 +448,27 @@ export const generatePostgresDdl = async (
                         if (required) colDef += " NOT NULL";
                         columns.push(colDef);
 
-                        fkStatements.push(`ALTER TABLE "${schema}"."${baseTableName}" ADD CONSTRAINT "${baseTableName}_${colName}_fkey" FOREIGN KEY ("${colName}") REFERENCES "${targetSchema}"."${targetTable}" ("${targetId}") ON DELETE ${onDelete.toUpperCase()};`);
+                        fkStatements.push(`ALTER TABLE "${schema}"."${baseTableName}" ADD CONSTRAINT "${toPostgresIdentifier(`${baseTableName}_${colName}_fkey`)}" FOREIGN KEY ("${colName}") REFERENCES "${targetSchema}"."${targetTable}" ("${targetId}") ON DELETE ${onDelete.toUpperCase()};`);
                     }
                 } else {
                     const colName = resolveColumnName(propName, prop);
+
+                    // On an auth collection, the columns auth reads and writes
+                    // are defined once, in `auth-users-columns`, and every
+                    // creator of this table emits that definition. Before this,
+                    // the desired state here was built from the collection file
+                    // alone — which knows nothing of `is_anonymous` or
+                    // `tokens_valid_after` — so `db push` and the runtime
+                    // disagreed about `email`'s nullability and about which
+                    // columns exist at all.
+                    const authDefinition = isAuthCollection(collection)
+                        ? authUsersColumnDefinition(colName)
+                        : undefined;
+                    if (authDefinition && !isIdProperty(propName, prop, collection)) {
+                        columns.push(`  "${colName}" ${authDefinition}`);
+                        return;
+                    }
+
                     const colType = getSqlColumnType(propName, prop, collection, collections);
                     let colDef = `  "${colName}" ${colType}`;
 
@@ -428,6 +505,27 @@ export const generatePostgresDdl = async (
                 }
             });
 
+            // ── Auth columns the collection file never mentions ──────────────
+            // `db push` is declarative: Atlas diffs the database against exactly
+            // what is emitted here and drops anything else. The scaffold's users
+            // collection describes 12 columns while auth needs 14, so
+            // `is_anonymous` and `tokens_valid_after` — created at boot by
+            // `ensureAuthTablesExist` — read as unmanaged drift, and a push run
+            // after the server had started once planned to DROP them. The
+            // destructive gate catches it, which makes it a data-loss prompt on
+            // the auth table rather than silent damage; either way the desired
+            // state was wrong. Emit the full contract so the two agree.
+            if (isAuthCollection(collection)) {
+                const declared = new Set(
+                    Object.entries(collection.properties ?? {})
+                        .map(([name, prop]) => resolveColumnName(name, prop))
+                );
+                for (const spec of AUTH_USERS_COLUMNS) {
+                    if (declared.has(spec.column)) continue;
+                    columns.push(`  "${spec.column}" ${authUsersColumnSql(spec)}`);
+                }
+            }
+
             // Backwards compatibility: add default id primary key if missing
             const hasPk = columns.some(c => c.includes("PRIMARY KEY"));
             if (!hasPk) {
@@ -470,7 +568,356 @@ export const generatePostgresDdl = async (
     return ddl;
 };
 
-export const generatePostgresPoliciesDdl = (collections: CollectionConfig[]): string => {
+/** The RLS statements one declared collection's table needs, ready to run. */
+/**
+ * A foreign key, as both its parts and the statement that creates it.
+ *
+ * `ALTER TABLE … ADD CONSTRAINT` has no `IF NOT EXISTS`, so a caller applying
+ * these has to skip by name — hence the name is a field and not only a substring
+ * of the SQL.
+ */
+export interface ForeignKeyPlan {
+    constraintName: string;
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    column: string;
+    targetSchema: string;
+    targetTable: string;
+    targetColumn: string;
+    sql: string;
+}
+
+/** A column a `relation` or `reference` property owns on its own table. */
+export interface RelationalColumnPlan {
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    column: string;
+    /** Postgres type, exactly as the DDL generator declares it. */
+    type: string;
+    /** Absent when the target collection is not part of this bundle. */
+    foreignKey?: ForeignKeyPlan;
+    /**
+     * What this column would have been called before `generateForeignKeyName`
+     * learned to singularize — set only when the two differ and the column name
+     * is the derived default rather than one the author wrote.
+     *
+     * Carried so the boot-time ensure can notice a database provisioned under
+     * the old rule. It is never used to name anything.
+     */
+    legacyColumn?: string;
+}
+
+/** The table behind a many-to-many `through` relation. */
+export interface JunctionTablePlan {
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    columns: { name: string; type: string; legacyName?: string }[];
+    /** Both endpoint columns plus the composite primary key. */
+    createTable: string;
+    foreignKeys: ForeignKeyPlan[];
+}
+
+const schemaOfCollection = (collection: CollectionConfig): string =>
+    isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
+
+const bareTableName = (name: string): string => (name.includes(".") ? name.split(".").pop()! : name);
+
+/**
+ * Truncate a derived identifier the way Postgres does: to 63 bytes, silently.
+ *
+ * This is not cosmetic, and not really a naming choice at all — it is agreeing
+ * with the name the database ALREADY stored. `ADD CONSTRAINT` on a longer name
+ * succeeds and records the truncated form, so the untruncated name this used to
+ * derive matched nothing in the catalogue. Boot-ensure compares its planned
+ * constraints against `readExistingSchema`, which reads catalogue names, so the
+ * comparison could never hit: every boot re-issued `ADD CONSTRAINT` for the same
+ * constraint, forever, and got "already exists" every time. Non-fatal (foreign
+ * keys are the one action allowed to fail) and therefore permanent — an error in
+ * the log on every restart of a project whose table and column names happened to
+ * be long.
+ *
+ * Byte length, not string length: NAMEDATALEN is 64 bytes, and a multi-byte
+ * character straddling the boundary would be cut mid-sequence by `slice(0, 63)`.
+ */
+const toPostgresIdentifier = (name: string): string => {
+    const bytes = Buffer.from(name, "utf8");
+    if (bytes.byteLength <= 63) return name;
+    // `toString` on a slice that ends mid-character yields U+FFFD; dropping it
+    // lands on the last whole character that fits, which is what Postgres does.
+    return bytes.subarray(0, 63).toString("utf8").replace(/�+$/, "");
+};
+
+const foreignKeyPlan = (
+    args: Omit<ForeignKeyPlan, "constraintName" | "sql"> & { onDelete: string; onUpdate?: string }
+): ForeignKeyPlan => {
+    const constraintName = toPostgresIdentifier(`${args.table}_${args.column}_fkey`);
+    const onUpdate = args.onUpdate ? ` ON UPDATE ${args.onUpdate.toUpperCase()}` : "";
+    return {
+        constraintName,
+        schema: args.schema,
+        table: args.table,
+        column: args.column,
+        targetSchema: args.targetSchema,
+        targetTable: args.targetTable,
+        targetColumn: args.targetColumn,
+        sql:
+            `ALTER TABLE "${args.schema}"."${args.table}" ADD CONSTRAINT "${constraintName}" ` +
+            `FOREIGN KEY ("${args.column}") REFERENCES "${args.targetSchema}"."${args.targetTable}" ` +
+            `("${args.targetColumn}") ON DELETE ${args.onDelete.toUpperCase()}${onUpdate};`
+    };
+};
+
+/**
+ * The FK columns the declared collections own — one entry per `relation`
+ * (`belongsTo` side) or `reference` property.
+ *
+ * Split out of {@link generatePostgresDdl} so the boot-time schema ensure can
+ * create the same columns with the same names, types and constraints. Before
+ * this it skipped them outright, which was survivable only because `db push`
+ * always followed; on a managed tenant nothing follows, so a table arrived
+ * without the column its own collection reads and wrote 400 on every insert.
+ *
+ * A relation whose target is not in the bundle yields no column at all (the
+ * generator returns early on an unresolvable target); a `reference` whose target
+ * is unknown yields the column without a constraint. Both mirror the generator
+ * exactly — a divergence here is a schema fork between boot and `db push`.
+ */
+export const planRelationalColumns = (allCollections: CollectionConfig[]): RelationalColumnPlan[] => {
+    const collections = relationalCollections(allCollections);
+    const plans: RelationalColumnPlan[] = [];
+
+    for (const collection of collections) {
+        const tableName = getTableName(collection);
+        if (!tableName) continue;
+        const schema = schemaOfCollection(collection);
+        const table = bareTableName(tableName);
+
+        for (const [propName, rawProp] of Object.entries(collection.properties ?? {})) {
+            const prop = rawProp as Property;
+
+            if (prop.type === "relation") {
+                const refProp = prop as RelationProperty;
+                const resolvedRelations = resolveCollectionRelations(collection);
+                const relInfo = findRelation(resolvedRelations, refProp.relation?.relationName ?? propName);
+                if (relInfo?.kind !== "belongsTo") continue;
+                // The relation and an explicit FK property can both be declared;
+                // the explicit one owns the column.
+                if (collection.properties[relInfo.localKey] && propName !== relInfo.localKey) continue;
+
+                let targetCollection: CollectionConfig;
+                try {
+                    targetCollection = relInfo.target();
+                } catch {
+                    continue;
+                }
+                if (!targetCollection) continue;
+
+                const required = prop.validation?.required;
+                // Only a *derived* column name can be affected by the change to
+                // `generateForeignKeyName`; one the author wrote is theirs.
+                const relationName = refProp.relation?.relationName ?? propName;
+                const legacyKey = legacyForeignKeyName(relationName);
+                const derived = relInfo.localKey === generateForeignKeyName(relationName);
+                plans.push({
+                    schema,
+                    table,
+                    column: relInfo.localKey,
+                    legacyColumn: derived && legacyKey !== relInfo.localKey ? legacyKey : undefined,
+                    type: getSqlColumnType(propName, prop, collection, collections),
+                    foreignKey: foreignKeyPlan({
+                        schema,
+                        table,
+                        column: relInfo.localKey,
+                        targetSchema: schemaOfCollection(targetCollection),
+                        targetTable: bareTableName(getTableName(targetCollection)),
+                        targetColumn: getPrimaryKeyName(targetCollection),
+                        onDelete: relInfo.onDelete ?? (required ? "CASCADE" : "SET NULL"),
+                        onUpdate: relInfo.onUpdate
+                    })
+                });
+            } else if (prop.type === "reference") {
+                const refProp = prop as ReferenceProperty;
+                const targetCollection = collections.find(
+                    c => c.slug === refProp.path || getTableName(c) === refProp.path
+                );
+                const column = resolveColumnName(propName, prop);
+                const type = getSqlColumnType(propName, prop, collection, collections);
+                const required = prop.validation?.required;
+
+                plans.push({
+                    schema,
+                    table,
+                    column,
+                    type,
+                    foreignKey: targetCollection
+                        ? foreignKeyPlan({
+                            schema,
+                            table,
+                            column,
+                            targetSchema: schemaOfCollection(targetCollection),
+                            targetTable: bareTableName(getTableName(targetCollection)),
+                            targetColumn: getPrimaryKeyName(targetCollection),
+                            onDelete: required ? "CASCADE" : "SET NULL"
+                        })
+                        : undefined
+                });
+            }
+        }
+    }
+
+    return plans;
+};
+
+/**
+ * The junction tables a bundle's many-to-many relations imply.
+ *
+ * Derived from {@link resolveJunctionSpecs}, the same source the junction RLS
+ * comes from, so a table created here always has policies planned for it — a
+ * junction with row-level security left off is readable and writable by every
+ * signed-in user, which is why the two must ship together.
+ */
+export const planJunctionTables = (allCollections: CollectionConfig[]): JunctionTablePlan[] => {
+    const collections = relationalCollections(allCollections);
+    const plans: JunctionTablePlan[] = [];
+
+    for (const spec of resolveJunctionSpecs(collections).values()) {
+        const [source, target] = spec.endpoints;
+        // A junction column's default name is derived from the endpoint
+        // collection's slug — which is normally plural, so this is where the
+        // singularization change actually lands: a `categories` endpoint used
+        // to give `categorie_id` and now gives `category_id`. Recorded, not
+        // used, so boot-ensure can recognise a table built under the old rule.
+        const legacyFor = (endpoint: typeof source): string | undefined => {
+            const slug = toSnakeCase(endpoint.collection.slug ?? endpoint.collection.name ?? "");
+            const legacy = legacyForeignKeyName(slug);
+            const derived = endpoint.junctionColumn === generateForeignKeyName(slug);
+            return derived && legacy !== endpoint.junctionColumn ? legacy : undefined;
+        };
+        const columns = [
+            { name: source.junctionColumn, type: junctionKeyType(source.collection), legacyName: legacyFor(source) },
+            { name: target.junctionColumn, type: junctionKeyType(target.collection), legacyName: legacyFor(target) }
+        ];
+        // Every declaring side agrees on the edge's lifetime; the first one wins,
+        // as it does in the generator's walk.
+        const onDelete = spec.declaringSides[0]?.relation.onDelete ?? "CASCADE";
+
+        plans.push({
+            schema: spec.schema,
+            table: spec.table,
+            columns,
+            createTable:
+                `CREATE TABLE IF NOT EXISTS "${spec.schema}"."${spec.table}" (` +
+                columns.map(c => `"${c.name}" ${c.type} NOT NULL`).join(", ") +
+                `, PRIMARY KEY (${columns.map(c => `"${c.name}"`).join(", ")}));`,
+            foreignKeys: [source, target].map((endpoint, i) =>
+                foreignKeyPlan({
+                    schema: spec.schema,
+                    table: spec.table,
+                    column: columns[i].name,
+                    targetSchema: schemaOfCollection(endpoint.collection),
+                    targetTable: bareTableName(getTableName(endpoint.collection)),
+                    targetColumn: getPrimaryKeyName(endpoint.collection),
+                    onDelete
+                })
+            )
+        });
+    }
+
+    return plans;
+};
+
+export interface CollectionPolicyPlan {
+    /** The table's schema (e.g. `public`, `rebase`). */
+    schema: string;
+    /** The bare table name, no schema prefix. */
+    table: string;
+    /** `schema.table` — matches the keys `readExistingSchema` returns. */
+    qualified: string;
+    /** `ALTER TABLE … ENABLE ROW LEVEL SECURITY;` — locked by default. */
+    enableRls: string;
+    /** `DROP POLICY IF EXISTS` / `CREATE POLICY` statements, in order. */
+    policyStatements: string[];
+}
+
+/**
+ * The per-table RLS plan for the *declared* collections, as executable
+ * statements — what the managed runtime applies at boot so a freshly
+ * provisioned tenant database serves data instead of 401ing every read.
+ *
+ * Mirrors {@link generatePostgresPoliciesDdl} exactly (same
+ * `generatePolicyStatements`, same enable-RLS, same effective rules, same
+ * derived junction rules), so boot and `db push` produce identical policies from
+ * identical collections.
+ *
+ * Junction tables are included, and have to be: boot creates them now
+ * ({@link planJunctionTables}), and a junction with RLS left off is readable and
+ * writable by every signed-in user. A junction whose table is still absent is
+ * skipped by the applier, not planned away here.
+ */
+export const planCollectionPolicies = (allCollections: CollectionConfig[]): CollectionPolicyPlan[] => {
+    // A store with no RLS gets no policies planned for it — `supportsRLS` is
+    // false for exactly the engines `relationalCollections` filters out.
+    const collections = relationalCollections(allCollections);
+    const resolveCollection: ResolveCollection = (slug) => collections.find(c => c.slug === slug || getTableName(c) === slug);
+    const plans: CollectionPolicyPlan[] = [];
+    const seen = new Set<string>();
+
+    for (const collection of collections) {
+        const tableName = getTableName(collection);
+        if (!tableName) continue;
+        const schema = isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
+        const baseTableName = tableName.includes(".") ? tableName.split(".").pop()! : tableName;
+        const qualified = `${schema}.${baseTableName}`;
+        if (seen.has(qualified)) continue;
+        seen.add(qualified);
+
+        const policyStatements: string[] = [];
+        for (const rule of getEffectiveSecurityRules(collection)) {
+            policyStatements.push(...generatePolicyStatements(collection, rule, resolveCollection));
+        }
+
+        plans.push({
+            schema,
+            table: baseTableName,
+            qualified,
+            enableRls: `ALTER TABLE "${schema}"."${baseTableName}" ENABLE ROW LEVEL SECURITY;`,
+            policyStatements
+        });
+    }
+
+    // Junctions are derived from `through` relations rather than declared, so
+    // the walk above never sees them.
+    for (const spec of resolveJunctionSpecs(collections).values()) {
+        const qualified = `${spec.schema}.${spec.table}`;
+        if (seen.has(qualified)) continue;
+        seen.add(qualified);
+
+        const junctionCollection = getJunctionCollectionConfig(spec);
+        const policyStatements: string[] = [];
+        for (const rule of getJunctionSecurityRules(spec)) {
+            policyStatements.push(...generatePolicyStatements(junctionCollection, rule, resolveCollection));
+        }
+
+        plans.push({
+            schema: spec.schema,
+            table: spec.table,
+            qualified,
+            enableRls: `ALTER TABLE "${spec.schema}"."${spec.table}" ENABLE ROW LEVEL SECURITY;`,
+            policyStatements
+        });
+    }
+
+    return plans;
+};
+
+export const generatePostgresPoliciesDdl = (allCollections: CollectionConfig[]): string => {
+    // Also the expectation `checkPolicyDrift` reconciles the database against,
+    // so a non-SQL collection filtered out here is one the drift report cannot
+    // invent a missing policy for.
+    const collections = relationalCollections(allCollections);
     let ddl = "-- This file contains RLS policies generated by Rebase. Applied separately from migrations.\n\n";
 
     const allTablesToGenerate = new Map<string, {