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

package/src/schema/generate-drizzle-schema-logic.ts

@@ -1,6 +1,6 @@
 import { CollectionConfig, NumberProperty, Property, ResolvedRelation, RelationProperty, SecurityOperation, SecurityRule, StringProperty, isPostgresCollectionConfig, DateProperty, ArrayProperty, MapProperty, ReferenceProperty, VectorProperty, BinaryProperty, isManyToMany, type ResolvedManyToMany, type ResolvedBelongsTo, type ResolvedForeignKeyOnTarget, hasForeignKeyOnTarget } from "@rebasepro/types";
 import { getPrimaryKeys } from "../services/collection-helpers";
-import { getEnumVarName, getTableName, getTableVarName, resolveCollectionRelations, findRelation, securityRuleToConditions, policyToPostgres, getEffectiveSecurityRules, resolveJunctionSpecs, getJunctionSecurityRules, getJunctionCollectionConfig } from "@rebasepro/common";
+import { getEnumVarName, getTableName, getTableVarName, resolveCollectionRelations, findRelation, securityRuleToConditions, policyToPostgres, getEffectiveSecurityRules, resolveJunctionSpecs, getJunctionSecurityRules, getJunctionCollectionConfig, resolveStringColumnLength } from "@rebasepro/common";
 import { toSnakeCase, getPolicyNamesForRule } from "@rebasepro/utils";
 import { logger } from "@rebasepro/server";
 // --- Helper Functions ---
@@ -98,9 +98,13 @@ const getDrizzleColumn = (propName: string, prop: Property, collection: Collecti
             } else if (stringProp.columnType === "uuid") {
                 columnDefinition = `uuid("${colName}")`;
             } else if (stringProp.columnType === "char") {
-                columnDefinition = `char("${colName}")`;
+                columnDefinition = `char("${colName}", { length: ${resolveStringColumnLength(stringProp)} })`;
             } else if (stringProp.columnType === "varchar") {
-                columnDefinition = `varchar("${colName}")`;
+                // The length is not optional decoration: `varchar("col")` with
+                // no length is an UNBOUNDED varchar in Postgres, which is what
+                // this emitted while the DDL generator emitted VARCHAR(255) for
+                // the very same property.
+                columnDefinition = `varchar("${colName}", { length: ${resolveStringColumnLength(stringProp)} })`;
             } else {
                 // `text` is the default, and the only length-unbounded choice.
                 // Ask for `varchar` explicitly if you want the length constraint.

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

@@ -1,5 +1,5 @@
 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 { getEnumVarName, getTableName, resolveCollectionRelations, findRelation, securityRuleToConditions, policyToPostgres, getEffectiveSecurityRules, getInjectedSecurityRules, resolveJunctionSpecs, getJunctionSecurityRules, getJunctionCollectionConfig, resolveStringColumnLength } from "@rebasepro/common";
 import { toSnakeCase, getPolicyNamesForRule } from "@rebasepro/utils";
 
 // --- Helper Functions ---
@@ -11,7 +11,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 +28,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 +49,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 +78,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,11 +108,12 @@ 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];
 };
 
 export const getSqlColumnType = (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]): string => {
@@ -103,11 +129,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
@@ -470,6 +500,295 @@ export const generatePostgresDdl = async (
     return ddl;
 };
 
+/** 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;
+}
+
+/** 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 }[];
+    /** 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);
+
+const foreignKeyPlan = (
+    args: Omit<ForeignKeyPlan, "constraintName" | "sql"> & { onDelete: string; onUpdate?: string }
+): ForeignKeyPlan => {
+    const constraintName = `${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 = (collections: CollectionConfig[]): RelationalColumnPlan[] => {
+    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;
+                plans.push({
+                    schema,
+                    table,
+                    column: relInfo.localKey,
+                    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 = (collections: CollectionConfig[]): JunctionTablePlan[] => {
+    const plans: JunctionTablePlan[] = [];
+
+    for (const spec of resolveJunctionSpecs(collections).values()) {
+        const [source, target] = spec.endpoints;
+        const columns = [
+            { name: source.junctionColumn, type: junctionKeyType(source.collection) },
+            { name: target.junctionColumn, type: junctionKeyType(target.collection) }
+        ];
+        // 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 = (collections: CollectionConfig[]): CollectionPolicyPlan[] => {
+    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 = (collections: CollectionConfig[]): string => {
     let ddl = "-- This file contains RLS policies generated by Rebase. Applied separately from migrations.\n\n";
 

package/src/schema/introspect-runtime.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, it } from "@jest/globals";
+import { resolveCollectionRelations } from "@rebasepro/common";
+import type { CollectionConfig } from "@rebasepro/types";
 
 import { buildCollectionsFromSchema, introspectSchema, readRlsStatus, IntrospectedSchema, Queryable } from "./introspect-runtime";
 import { buildTablesMap, identifyJoinTables, TableColumn, ForeignKeyRow, PrimaryKeyRow } from "./introspect-db-logic";
@@ -121,14 +123,60 @@ describe("buildCollectionsFromSchema", () => {
         const props = posts.properties as any;
 
         expect(props.author_id).toBeUndefined();
-        expect(props.author).toEqual({
-            name: "Author",
-            type: "relation",
-            target: "authors",
-            cardinality: "one",
-            direction: "owning",
-            localKey: "author_id"
-        });
+        expect(props.author.name).toBe("Author");
+        expect(props.author.type).toBe("relation");
+        // The descriptor is nested under `relation`, carries `kind`, and its
+        // `target` is a thunk — see the resolvability test below for why none of
+        // those three are stylistic.
+        expect(props.author.relation).toMatchObject({ kind: "belongsTo", localKey: "author_id" });
+        expect(typeof props.author.relation.target).toBe("function");
+        expect(props.author.relation.target().slug).toBe("authors");
+    });
+
+    /**
+     * The shape has to be one the resolver actually reads.
+     *
+     * This path emitted `cardinality` / `direction` / a bare-string `target`
+     * flat on the property — the shape `Relation` stopped accepting, and the
+     * same drift `introspect-emits-valid-relations.test.ts` caught in the
+     * generated-file path and this one was missed by. Nothing threw:
+     * `resolveCollectionRelations` reads `property.relation`, found none, and
+     * reported a collection with no relations at all.
+     *
+     * The visible cost was writes. `assertKnownWriteFields` learns an owning
+     * relation's FK column from the *resolved* relation's `localKey`, and the FK
+     * column is deliberately absent from `properties` ("surfaces as a
+     * relation"), so with nothing resolving, `POST /api/data/orders` with
+     * `product_id` came back 400 `has no field 'product_id'` — the column was
+     * simultaneously the only way to set the relation and not a known field.
+     *
+     * Asserting the literal object is what let it drift, so this asserts
+     * through the resolver instead: a future reshape has to keep it resolvable,
+     * not merely keep the keys someone once wrote down.
+     */
+    it("emits a relation the resolver can read, so the fk column is writable", () => {
+        const schema = schemaOf(
+            [
+                column({ table_name: "products", column_name: "id", data_type: "integer", udt_name: "int4", is_nullable: "NO" }),
+                column({ table_name: "orders", column_name: "id", data_type: "integer", udt_name: "int4", is_nullable: "NO" }),
+                column({ table_name: "orders", column_name: "product_id", data_type: "integer", udt_name: "int4" })
+            ],
+            [
+                { table_name: "products", column_name: "id" },
+                { table_name: "orders", column_name: "id" }
+            ],
+            [{ table_name: "orders", column_name: "product_id", foreign_table_name: "products", foreign_column_name: "id" }]
+        );
+
+        const orders = buildCollectionsFromSchema(schema, "public").find((c) => c.slug === "orders")!;
+        const resolved = resolveCollectionRelations(orders as unknown as CollectionConfig);
+
+        expect(Object.keys(resolved)).toEqual(["product"]);
+        expect(resolved.product.kind).toBe("belongsTo");
+        // `localKey` is the field `assertKnownWriteFields` adds to the known set,
+        // which is what makes `product_id` writable. The write itself is covered
+        // end-to-end by `scripts/smoke-baas.ts` against a real database.
+        expect((resolved.product as { localKey: string }).localKey).toBe("product_id");
     });
 
     it("skips join tables — they are an edge between collections, not a collection", () => {

package/src/schema/introspect-runtime.ts

@@ -207,13 +207,30 @@ function buildProperties(
 }
 
 /**
- * Owning relations, derived from this table's foreign keys. Mirrors the shape
- * `generateCollectionFile` emits, except `target` uses the slug string form
- * rather than a thunk to a module import.
+ * Owning relations, derived from this table's foreign keys — the same shape
+ * `generateCollectionFile` writes into a collection file: a `relation` property
+ * whose nested descriptor carries `kind`, a `target` thunk and the `localKey`.
+ *
+ * The shape is load-bearing, not cosmetic. `resolveCollectionRelations` reads
+ * relations from `property.relation` and `resolveRelation` requires `target` to
+ * be a thunk; this used to emit `target`/`cardinality`/`localKey` flat on the
+ * property with the slug as a bare string, which satisfies neither. Nothing
+ * threw — the resolver simply skipped every such property and reported that the
+ * collection had no relations. So an introspected BaaS collection had its FK
+ * columns removed from `properties` (they "surface as relations") and then no
+ * resolvable relation to surface as, which is why writing the FK column
+ * directly came back as `has no field 'product_id'`: `assertKnownWriteFields`
+ * learns that column from the resolved relation's `localKey`.
+ *
+ * The thunk closes over the collections being built in this same pass rather
+ * than importing a module, which is what a runtime introspection has instead of
+ * generated files. It is called lazily, after the map is fully populated, so a
+ * table may reference one introspected later.
  */
 function buildRelations(
     meta: TableMeta,
-    slugByTable: Map<string, string>
+    slugByTable: Map<string, string>,
+    collectionBySlug: Map<string, PostgresCollectionConfig>
 ): Record<string, Record<string, unknown>> {
     const relations: Record<string, Record<string, unknown>> = {};
 
@@ -233,10 +250,11 @@ function buildRelations(
         relations[key] = {
             name: humanize(key),
             type: "relation",
-            target: targetSlug,
-            cardinality: "one",
-            direction: "owning",
-            localKey: fk.column_name
+            relation: {
+                kind: "belongsTo",
+                target: () => collectionBySlug.get(targetSlug),
+                localKey: fk.column_name
+            }
         };
     }
 
@@ -259,6 +277,9 @@ export function buildCollectionsFromSchema(
     }
 
     const collections: PostgresCollectionConfig[] = [];
+    // Filled as we go; the relation thunks read it lazily, so a table may point
+    // at one that has not been built yet at the moment its relation is created.
+    const collectionBySlug = new Map<string, PostgresCollectionConfig>();
 
     for (const [tableName, meta] of tablesMap) {
         if (joinTables.has(tableName)) continue;
@@ -273,11 +294,12 @@ export function buildCollectionsFromSchema(
             icon: getIconForTable(tableName),
             properties: {
                 ...buildProperties(meta, enumMap),
-                ...buildRelations(meta, slugByTable)
+                ...buildRelations(meta, slugByTable, collectionBySlug)
             }
         } as unknown as PostgresCollectionConfig;
 
         collections.push(collection);
+        collectionBySlug.set(tableName, collection);
     }
 
     return collections;

package/src/utils/pg-error-utils.ts

@@ -97,6 +97,52 @@ export function extractCauseMessage(error: unknown): string | null {
     return null;
 }
 
+/**
+ * Codes that mean "this connection will never work as configured".
+ *
+ * A wrong password or a database that does not exist is a settled fact about
+ * the connection string, not a transient fault — retrying produces the same
+ * answer forever.
+ */
+const UNRECOVERABLE_CONNECT_CODES = new Set([
+    "28P01", // invalid_password
+    "28000", // invalid_authorization_specification
+    "3D000", // invalid_catalog_name — the database does not exist
+    "42501"  // insufficient_privilege
+]);
+
+export interface ConnectFailure {
+    /** True when retrying cannot help: the connection string itself is wrong. */
+    fatal: boolean;
+    /** The deepest message available — the Postgres one where there is one. */
+    reason: string;
+    /** The `SQLSTATE`, when the failure came from Postgres rather than the socket. */
+    code?: string;
+}
+
+/**
+ * Describe a failed connection attempt in terms a developer can act on.
+ *
+ * The error a caller catches is Drizzle's wrapper: its message is
+ * `Failed query: SELECT 1` and its stack runs through drizzle internals, while
+ * the sentence that says what is actually wrong — "password authentication
+ * failed for user …", "database … does not exist" — sits in `.cause`. Logging
+ * the wrapper, as the bootstrapper used to, tells a developer with a typo in
+ * their `DATABASE_URL` nothing at all.
+ */
+export function classifyConnectFailure(error: unknown): ConnectFailure {
+    const pgError = extractPgError(error);
+    const reason =
+        pgError?.message ??
+        extractCauseMessage(error) ??
+        (error instanceof Error ? error.message : String(error));
+    return {
+        fatal: Boolean(pgError?.code && UNRECOVERABLE_CONNECT_CODES.has(pgError.code)),
+        reason,
+        code: pgError?.code
+    };
+}
+
 /**
  * Detect whether an error is specifically a role-switching permission failure
  * (e.g. "permission denied to set role" or "must be member of role"),