@rebasepro/server-postgres 0.16.1-canary.g2d1aec8 → 0.16.1-canary.g37d7b4f

package/src/schema/collection-index.ts

@@ -0,0 +1,427 @@
+/**
+ * The one place a collection's `indexes:` block becomes `CREATE INDEX`.
+ *
+ * Like `search-column.ts` and `vector-index.ts`, this module exists so the DDL
+ * generator and the boot-time ensure render the *same* specification rather
+ * than describing the same index twice, differently.
+ *
+ * ## Why every form here is core Postgres
+ *
+ * `rebase db push` runs `atlas schema apply`, which materialises the desired
+ * state in a bare scratch database to plan against. `--exclude` does not
+ * suppress that replay, and `CREATE EXTENSION` cannot go in the file. So an
+ * index wanting `gin_trgm_ops` or `vector_cosine_ops` would parse, plan, and
+ * then fail against a database the author has never heard of. Those are
+ * refused here instead, and redirected to the feature that owns them: trigram
+ * search is `search:`, ANN is a `vector` property.
+ *
+ * Verified against atlas v1.2.3 and Postgres 18 before this was written: plain,
+ * composite with `DESC NULLS LAST`, partial, unique, covering `INCLUDE`, `GIN`
+ * and expression indexes all parse, apply, and re-plan clean. The Atlas
+ * limitation that forced the search carve-out is that it will not parse a file
+ * containing a function *definition* — a function *call* inside an index is
+ * fine. That is why this module needs no carve-out and search did.
+ *
+ * ## Why the name carries a hash
+ *
+ * `CREATE INDEX IF NOT EXISTS` is a **name** check, not a definition check. A
+ * readable name means a changed declaration keeps the old index and reports
+ * success, forever. Hashing the index's *semantics* into its name makes a
+ * redefinition a different object: the new one is built before the old one is
+ * dropped, there is never a window with no index, and drift detection reduces
+ * to a set difference over names.
+ */
+import type { CollectionConfig, CollectionIndex, IndexPredicate, Property, ResolvedRelation } from "@rebasepro/types";
+import { isPostgresCollectionConfig } from "@rebasepro/types";
+import { getTableName, resolveCollectionRelations } from "@rebasepro/common";
+import { sha1Hex, truncateToBytes } from "@rebasepro/utils";
+
+/** Resolve a property key to its column name. Injected to avoid an import cycle. */
+export type ResolveColumnName = (propName: string, prop?: Property | null) => string;
+
+export type IndexMethod = "btree" | "gin" | "brin";
+
+/** A key column, with the ordering Postgres will actually apply. */
+export interface ResolvedIndexKey {
+    column: string;
+    /** Always concrete. `btree` defaults ascending; unordered methods report `asc`. */
+    direction: "asc" | "desc";
+    /** Postgres's own default: `last` under `asc`, `first` under `desc`. */
+    nulls: "first" | "last";
+}
+
+/** A predicate resolved onto column names, ready to render and to hash. */
+export type ResolvedPredicate =
+    | { column: string; op: "=" | "!=" | "<" | "<=" | ">" | ">="; value: string | number | boolean }
+    | { column: string; op: "is null" | "is not null" }
+    | { column: string; op: "in"; value: readonly (string | number)[] }
+    | { and: readonly ResolvedPredicate[] };
+
+/** One index, fully resolved. The only shape the renderers accept. */
+export interface CollectionIndexSpec {
+    schema: string;
+    table: string;
+    method: IndexMethod;
+    unique: boolean;
+    keys: ResolvedIndexKey[];
+    include: string[];
+    predicate: ResolvedPredicate | null;
+    /** The author's one-line justification. Never enters the name. */
+    reason: string;
+    /** Derived by {@link deriveIndexName}. Frozen — see the module comment. */
+    indexName: string;
+}
+
+/**
+ * A declaration that cannot become an index.
+ *
+ * Thrown at build time, naming the collection and the array position, because
+ * the alternative is a `CREATE INDEX` that fails during a push with a Postgres
+ * error mentioning a column the author never wrote.
+ */
+export class CollectionIndexConfigError extends Error {
+    readonly collectionSlug: string;
+    readonly position: number;
+
+    constructor(collectionSlug: string, position: number, message: string) {
+        super(`${collectionSlug}.indexes[${position}]: ${message}`);
+        this.name = "CollectionIndexConfigError";
+        this.collectionSlug = collectionSlug;
+        this.position = position;
+    }
+}
+
+/** Postgres allows 32 key columns. See the doc comment on `on`. */
+export const MAX_INDEX_KEYS = 5;
+
+/**
+ * `_ix`/`_ux` plus `_` plus 7 hex — the part of the name that must always
+ * survive truncation, and therefore is never inside the truncated portion.
+ */
+const NAME_SUFFIX_BYTES = 11;
+
+/**
+ * Every Rebase-managed index name, and nothing else.
+ *
+ * The terminal `_ix_`/`_ux_` plus exactly seven lowercase hex characters is
+ * what separates this scheme from every other producer in the codebase —
+ * `_fkey`, `_gin`, `_trgm`, `_pkey`, `_key`, the vector distances, and the
+ * `idx_` prefix auth uses. `_idx` was rejected as a tail because it is already
+ * taken for real: `users_email_verification_token_idx` is byte-for-byte what a
+ * naive `<table>_<column>_idx` derives on an auth-enabled `users` collection.
+ *
+ * Load-bearing for safety, not just tidiness. An index that does NOT match this
+ * belongs to somebody else — a hand-written one, or one an introspected
+ * database arrived with — and is excluded from the Atlas diff so the push
+ * cannot drop it.
+ */
+export const isRebaseIndexName = (name: string): boolean => /_(?:ix|ux)_[0-9a-f]{7}$/.test(name);
+
+const isOrderedMethod = (method: IndexMethod): boolean => method === "btree";
+
+/**
+ * The parts of an index that decide what it *is*.
+ *
+ * A semantic projection, not the rendered statement — the same arrangement as
+ * `getPolicyNameHash`, and for the same reason. A change to how this file
+ * formats SQL (eliding a default `USING btree`, quoting differently, emitting
+ * `NULLS LAST` explicitly) must not silently rename every index in every
+ * deployed database. Hashing generator output would make every cosmetic edit a
+ * fleet-wide DROP + CREATE.
+ *
+ * `reason` is deliberately absent: rewording a comment must not rebuild an
+ * index. `nulls` is the *effective* placement, so writing Postgres's own
+ * default down is a no-op rather than a redefinition.
+ *
+ * `v` is the only escape hatch, and it is expensive on purpose: bumping it
+ * renames every index in the field.
+ */
+export const indexFingerprint = (spec: Omit<CollectionIndexSpec, "indexName">): string => sha1Hex(JSON.stringify({
+    v: 1,
+    s: spec.schema,
+    t: spec.table,
+    m: spec.method,
+    u: spec.unique,
+    k: spec.keys.map(k => [k.column, k.direction, k.nulls]),
+    i: spec.include,
+    w: spec.predicate
+})).substring(0, 7);
+
+/**
+ * `<table>_<columns>_ix_<hash>`, or `_ux_` when unique.
+ *
+ * Truncation eats the readable head and never the hash. `toPostgresIdentifier`
+ * truncates the whole string at 63 bytes, which on a hashed name would cut off
+ * the one part that makes it unique — the failure already frozen into
+ * `contracts/derived-names.txt`, where a foreign key is recorded with its
+ * `_fkey` suffix truncated away, so a second foreign key on that table would
+ * derive a byte-identical name.
+ */
+export const deriveIndexName = (spec: Omit<CollectionIndexSpec, "indexName">): string => {
+    // Built suffix-first, so the two parts that carry meaning — the `_ix`/`_ux`
+    // tag that {@link isRebaseIndexName} matches on, and the fingerprint — are
+    // never in the string being truncated. Composing the whole name and then
+    // trimming it to 63 loses both, silently: an 80-byte table name yields
+    // `xxxx…xxx_610bb9e` with the tag gone, so the index stops being
+    // recognisable as Rebase's and `db push` treats it as foreign forever.
+    const tag = spec.unique ? "ux" : "ix";
+    const suffix = `_${tag}_${indexFingerprint(spec)}`;
+    const readable = `${spec.table}_${spec.keys.map(k => k.column).join("_")}`;
+    return `${truncateToBytes(readable, 63 - NAME_SUFFIX_BYTES)}${suffix}`;
+};
+
+const quoteLiteral = (value: string | number | boolean): string => {
+    if (typeof value === "number") return String(value);
+    if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+    return `'${value.replace(/'/g, "''")}'`;
+};
+
+/** Render a resolved predicate as the body of a `WHERE` clause. */
+export const renderPredicate = (predicate: ResolvedPredicate): string => {
+    if ("and" in predicate) {
+        // Always parenthesised. Postgres would apply the same precedence
+        // without it, but the rendered SQL is read by people diffing a plan.
+        return predicate.and.map(renderPredicate).join(" AND ");
+    }
+    switch (predicate.op) {
+        case "is null":
+        case "is not null":
+            return `"${predicate.column}" ${predicate.op.toUpperCase()}`;
+        case "in":
+            return `"${predicate.column}" IN (${predicate.value.map(quoteLiteral).join(", ")})`;
+        default:
+            return `"${predicate.column}" ${predicate.op} ${quoteLiteral(predicate.value)}`;
+    }
+};
+
+/**
+ * The `CREATE INDEX` for one spec.
+ *
+ * `concurrently` is a parameter rather than a string replacement on the way
+ * out. `search-column.ts` and `vector-index.ts` both reach for
+ * `.replace("CREATE INDEX IF NOT EXISTS", …)` instead, which silently does
+ * nothing for a UNIQUE index — the rendered text is `CREATE UNIQUE INDEX …`
+ * and the pattern never matches.
+ */
+export const collectionIndexStatement = (
+    spec: CollectionIndexSpec,
+    options: { concurrently?: boolean; ifNotExists?: boolean } = {}
+): string => {
+    const unique = spec.unique ? "UNIQUE " : "";
+    const concurrently = options.concurrently ? "CONCURRENTLY " : "";
+    const ifNotExists = options.ifNotExists ? "IF NOT EXISTS " : "";
+    const using = spec.method === "btree" ? "" : ` USING ${spec.method}`;
+
+    const keys = spec.keys.map(k => {
+        if (!isOrderedMethod(spec.method)) return `"${k.column}"`;
+        const direction = k.direction === "desc" ? " DESC" : "";
+        // Emitted only when it is not what the direction already implies, so
+        // the rendered SQL matches what `pg_get_indexdef` reads back and a
+        // re-plan finds no difference.
+        const impliedNulls = k.direction === "desc" ? "first" : "last";
+        const nulls = k.nulls === impliedNulls ? "" : ` NULLS ${k.nulls.toUpperCase()}`;
+        return `"${k.column}"${direction}${nulls}`;
+    }).join(", ");
+
+    const include = spec.include.length > 0
+        ? ` INCLUDE (${spec.include.map(c => `"${c}"`).join(", ")})`
+        : "";
+    const where = spec.predicate ? ` WHERE ${renderPredicate(spec.predicate)}` : "";
+
+    return `CREATE ${unique}INDEX ${concurrently}${ifNotExists}"${spec.indexName}" ` +
+        `ON "${spec.schema}"."${spec.table}"${using} (${keys})${include}${where};`;
+};
+
+export const collectionIndexStatements = (
+    specs: readonly CollectionIndexSpec[],
+    options: { concurrently?: boolean; ifNotExists?: boolean } = {}
+): string[] => specs.map(spec => collectionIndexStatement(spec, options));
+
+const relationOf = (
+    collection: CollectionConfig,
+    propKey: string
+): ResolvedRelation | undefined => resolveCollectionRelations(collection)[propKey];
+
+/**
+ * The column a property key indexes.
+ *
+ * A `belongsTo` resolves to its `localKey` — `primaryCategory` becomes
+ * `primary_category_id` — which is the case an index is most often wanted for
+ * and the case where the property key and the column differ. Everything else
+ * goes through `resolveColumnName`.
+ *
+ * The other relation kinds have no local column at all: the foreign key lives
+ * on the target's table, or in a junction. Indexing them here is refused
+ * rather than resolved to a column that does not exist.
+ */
+export const resolveIndexableColumn = (
+    collection: CollectionConfig,
+    propKey: string,
+    resolveColumnName: ResolveColumnName,
+    fail: (message: string) => never
+): string => {
+    const relation = relationOf(collection, propKey);
+    if (relation) {
+        if (relation.kind === "belongsTo") return relation.localKey;
+        fail(
+            `"${propKey}" is a ${relation.kind} relation, which has no column on this table — ` +
+            `the foreign key lives on "${relation.targetSlug}". Declare the index there.`
+        );
+    }
+
+    const property = collection.properties?.[propKey] as Property | undefined;
+    if (!property) {
+        fail(`"${propKey}" is not a property of this collection.`);
+    }
+    return resolveColumnName(propKey, property);
+};
+
+const resolvePredicate = (
+    collection: CollectionConfig,
+    predicate: IndexPredicate,
+    resolveColumnName: ResolveColumnName,
+    fail: (message: string) => never
+): ResolvedPredicate => {
+    if ("and" in predicate) {
+        return { and: predicate.and.map(p => resolvePredicate(collection, p, resolveColumnName, fail)) };
+    }
+    const column = resolveIndexableColumn(collection, predicate.prop, resolveColumnName, fail);
+    switch (predicate.op) {
+        case "is null":
+        case "is not null":
+            return { column, op: predicate.op };
+        case "in": {
+            const seen = new Set(predicate.value);
+            if (seen.size !== predicate.value.length) {
+                fail(`the \`in\` list for "${predicate.prop}" repeats a value, which changes nothing.`);
+            }
+            return { column, op: "in", value: [...predicate.value] };
+        }
+        default:
+            return { column, op: predicate.op, value: predicate.value };
+    }
+};
+
+/** The primary key columns of a collection, for the "you already have this" refusal. */
+const primaryKeyColumns = (collection: CollectionConfig, resolveColumnName: ResolveColumnName): string[] =>
+    Object.entries(collection.properties ?? {})
+        .filter(([, prop]) => prop && typeof prop === "object" && "isId" in prop && Boolean((prop as { isId?: unknown }).isId))
+        .map(([key, prop]) => resolveColumnName(key, prop as Property));
+
+/**
+ * Every index one collection declares, resolved and named.
+ *
+ * Throws {@link CollectionIndexConfigError} rather than dropping a bad entry:
+ * an index that silently does not exist is the failure mode this whole feature
+ * is here to remove.
+ */
+export const buildCollectionIndexSpecs = (
+    collection: CollectionConfig,
+    resolveColumnName: ResolveColumnName
+): CollectionIndexSpec[] => {
+    if (!isPostgresCollectionConfig(collection)) return [];
+    const declared = collection.indexes;
+    if (!declared || declared.length === 0) return [];
+
+    const slug = collection.slug ?? getTableName(collection);
+    const schema = collection.schema ?? "public";
+    const table = getTableName(collection);
+    const pk = primaryKeyColumns(collection, resolveColumnName).sort().join(",");
+
+    const specs: CollectionIndexSpec[] = [];
+    const byName = new Map<string, number>();
+
+    declared.forEach((index: CollectionIndex, position: number) => {
+        const fail = (message: string): never => {
+            throw new CollectionIndexConfigError(slug, position, message);
+        };
+
+        if (typeof index.reason !== "string" || index.reason.trim() === "") {
+            fail("`reason` is required — see the doc comment. An index nobody can justify is one nobody can delete.");
+        }
+        if (!Array.isArray(index.on) || index.on.length === 0) {
+            fail("`on` must name at least one property.");
+        }
+        if (index.on.length > MAX_INDEX_KEYS) {
+            fail(`\`on\` has ${index.on.length} keys; the limit is ${MAX_INDEX_KEYS}. Payload columns belong in \`include\`.`);
+        }
+
+        const method: IndexMethod = index.using ?? "btree";
+        const unique = method === "btree" && Boolean((index as { unique?: boolean }).unique);
+        if (!isOrderedMethod(method)) {
+            for (const key of index.on) {
+                if (typeof key !== "string" && ("direction" in key || "nulls" in key)) {
+                    fail(`access method "${method}" does not support ASC/DESC or NULLS options.`);
+                }
+            }
+        }
+
+        const keys: ResolvedIndexKey[] = index.on.map(key => {
+            const propKey = typeof key === "string" ? key : key.prop;
+            const column = resolveIndexableColumn(collection, propKey, resolveColumnName, fail);
+            const direction = (typeof key === "string" ? undefined : (key as { direction?: "asc" | "desc" }).direction) ?? "asc";
+            const nulls = (typeof key === "string" ? undefined : (key as { nulls?: "first" | "last" }).nulls)
+                ?? (direction === "desc" ? "first" : "last");
+            return { column, direction, nulls };
+        });
+
+        const duplicateKey = keys.map(k => k.column).find((c, i, all) => all.indexOf(c) !== i);
+        if (duplicateKey) fail(`"${duplicateKey}" appears twice in \`on\`.`);
+
+        if (keys.map(k => k.column).sort().join(",") === pk && pk !== "") {
+            fail(`this is the primary key — "${table}_pkey" already indexes exactly these columns.`);
+        }
+
+        const include = ((index as { include?: readonly string[] }).include ?? [])
+            .map(propKey => resolveIndexableColumn(collection, propKey, resolveColumnName, fail));
+        const overlap = include.find(c => keys.some(k => k.column === c));
+        if (overlap) fail(`"${overlap}" is in both \`on\` and \`include\`; Postgres rejects the overlap.`);
+
+        if (unique && keys.length === 1) {
+            const propKey = typeof index.on[0] === "string" ? index.on[0] as string : (index.on[0] as { prop: string }).prop;
+            const property = collection.properties?.[propKey] as { validation?: { unique?: boolean } } | undefined;
+            if (property?.validation?.unique) {
+                fail(
+                    `"${propKey}" already declares \`validation.unique\`, which compiles to an inline UNIQUE. ` +
+                    `Two declarations of one guarantee — remove one.`
+                );
+            }
+        }
+
+        const predicate = index.where
+            ? resolvePredicate(collection, index.where, resolveColumnName, fail)
+            : null;
+
+        const withoutName = { schema, table, method, unique, keys, include, predicate, reason: index.reason };
+        const indexName = deriveIndexName(withoutName);
+
+        const clash = byName.get(indexName);
+        if (clash !== undefined) {
+            fail(`derives the same name as indexes[${clash}] — they are the same index declared twice.`);
+        }
+        byName.set(indexName, position);
+
+        specs.push({ ...withoutName, indexName });
+    });
+
+    return specs;
+};
+
+/**
+ * Every declared index across a set of collections, in a stable order.
+ *
+ * Sorted because the result reaches `schema.sql`, which `doctor` string-
+ * compares against a regenerated copy — `generatePostgresDdl` does not sort its
+ * collections, so leaving this in declaration order would make the artifact
+ * depend on the order files happened to load in.
+ */
+export const buildCollectionIndexPlan = (
+    collections: readonly CollectionConfig[],
+    resolveColumnName: ResolveColumnName
+): CollectionIndexSpec[] =>
+    collections
+        .flatMap(collection => buildCollectionIndexSpecs(collection, resolveColumnName))
+        .sort((a, b) =>
+            a.schema.localeCompare(b.schema) ||
+            a.table.localeCompare(b.table) ||
+            a.indexName.localeCompare(b.indexName));

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

@@ -49,6 +49,7 @@ import {
     quoteSqlLiteral
 } from "./generate-postgres-ddl-logic";
 import { buildVectorIndexPlan, vectorIndexStatement, type SkippedVectorIndex } from "./vector-index";
+import { buildCollectionIndexPlan, collectionIndexStatement } from "./collection-index";
 import {
     AUTH_USERS_COLUMNS,
     authUsersColumnDefinition,
@@ -812,6 +813,26 @@ export function planCollectionSchemaEnsure(
         vectorIndexSkipped.push(...plan.skipped);
     }
 
+    //    Declared indexes, on exactly the same terms as the ANN ones above.
+    //
+    //    Boot has to emit these, not just `db push`: the managed runtime
+    //    provisions at boot and never runs a push, so a push-only index would
+    //    simply not exist there — and nothing would say so.
+    //    `contracts/derived-names.txt` states the rule ("Both, or it is a
+    //    bug") and the gate enforces it, which is what caught this.
+    //
+    //    `concurrently` is a parameter here rather than a string replacement
+    //    on the rendered SQL. The `.replace("CREATE INDEX IF NOT EXISTS", …)`
+    //    just above silently does nothing for a UNIQUE index, whose text is
+    //    `CREATE UNIQUE INDEX …` and never matches the pattern.
+    for (const spec of buildCollectionIndexPlan(collections, resolveColumnName)) {
+        actions.push({
+            kind: "create-index",
+            target: `${spec.schema}.${spec.table}`,
+            sql: collectionIndexStatement(spec, { concurrently: true, ifNotExists: true })
+        });
+    }
+
     return {
         actions,
         statements: actions.map(a => a.sql),

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

@@ -308,7 +308,12 @@ export const getDrizzleColumn = (propName: string, prop: Property, collection: C
             const targetTableVar = getTableVarName(getTableName(targetCollection));
             const pkProp = getPrimaryKeyProp(targetCollection);
             const targetIdField = pkProp.name;
-            const baseColumn = pkProp.type === "number" ? `integer("${fkColumnName}")` : (pkProp.isUuid ? `uuid("${fkColumnName}")` : `text("${fkColumnName}")`);
+            // `quote`, like every other column literal in this file: a column
+            // name only has to be quotable in Postgres, and this one is derived
+            // from a relation the author wrote.
+            const baseColumn = pkProp.type === "number"
+                ? `integer(${quote(fkColumnName)})`
+                : (pkProp.isUuid ? `uuid(${quote(fkColumnName)})` : `text(${quote(fkColumnName)})`);
 
             const onUpdate = relation.onUpdate ? `onUpdate: "${relation.onUpdate}"` : "";
             const required = prop.validation?.required;
@@ -681,10 +686,13 @@ export const generateSchema = async (allCollections: CollectionConfig[], stripPo
             const targetId = getPrimaryKeyName(targetCollection);
 
             schemaContent += `export const ${tableVarName} = ${tableCreator}(\"${baseTableName}\", {\n`;
-            schemaContent += `    ${sourceColumn}: ${sourceColType}(\"${sourceColumn}\").notNull().references(() => ${getTableVarName(getTableName(sourceCollection))}.${sourceId}, ${refOptions}),\n`;
-            schemaContent += `    ${targetColumn}: ${targetColType}(\"${targetColumn}\").notNull().references(() => ${getTableVarName(getTableName(targetCollection))}.${targetId}, ${refOptions}),\n`;
+            // The junction block was the one place these three helpers were not
+            // applied, so a junction column containing a space or a hyphen —
+            // both legal in Postgres — produced a file that does not parse.
+            schemaContent += `    ${propKey(sourceColumn)}: ${sourceColType}(${quote(sourceColumn)}).notNull().references(() => ${member(getTableVarName(getTableName(sourceCollection)), sourceId)}, ${refOptions}),\n`;
+            schemaContent += `    ${propKey(targetColumn)}: ${targetColType}(${quote(targetColumn)}).notNull().references(() => ${member(getTableVarName(getTableName(targetCollection)), targetId)}, ${refOptions}),\n`;
             schemaContent += "}, (table) => ([\n";
-            schemaContent += `    primaryKey({ columns: [table.${sourceColumn}, table.${targetColumn}] }),\n`;
+            schemaContent += `    primaryKey({ columns: [${member("table", sourceColumn)}, ${member("table", targetColumn)}] }),\n`;
 
             // Junctions are generated tables like any other: locked by default,
             // with derived policies (reads follow the endpoints, writes follow
@@ -719,19 +727,20 @@ export const generateSchema = async (allCollections: CollectionConfig[], stripPo
             const searchSpec = buildSearchColumnSpec(collection);
             if (searchSpec) {
                 columns.add(
-                    `    ${searchSpec.column}: customType({ dataType() { return 'tsvector'; } })("${searchSpec.column}")` +
+                    `    ${propKey(searchSpec.column)}: customType({ dataType() { return 'tsvector'; } })(${quote(searchSpec.column)})` +
                     `.generatedAlwaysAs(sql\`${searchSpec.expression}\`)`
                 );
                 if (searchSpec.fuzzy) {
                     columns.add(
-                        `    ${searchSpec.fuzzy.column}: text("${searchSpec.fuzzy.column}")` +
+                        `    ${propKey(searchSpec.fuzzy.column)}: text(${quote(searchSpec.fuzzy.column)})` +
                         `.generatedAlwaysAs(sql\`${searchSpec.fuzzy.expression}\`)`
                     );
                 }
             }
 
-            // Backwards compatibility: if no id/primary key column is found in properties, but `id` wasn't explicitly provided
-            // We should generate a basic id column if one was completely omitted.
+            // A collection that declares no primary key gets an implicit one:
+            // `id TEXT PRIMARY KEY`. The DDL generator emits the same column,
+            // and `derivePrimaryKeys` reads it back.
             const hasIdColumn = Array.from(columns).some(col => col.includes(".primaryKey()"));
             if (!hasIdColumn) {
                 columns.add("    id: text(\"id\").primaryKey()");
@@ -860,11 +869,14 @@ export const generateSchema = async (allCollections: CollectionConfig[], stripPo
                             // `fields`/`references` here is invalid and crashes
                             // `normalizeRelation` with "Cannot read properties of
                             // undefined (reading 'referencedTable')".
-                            tableRelations.push(`    "${relationKey}": one(${targetTableVar}, {\n        relationName: \"${drizzleRelationName}\"\n    })`);
+                            // A `relationName` is authored, and a `"` in one
+                            // closed this string literal early — in a file that
+                            // is compiled and imported by the server.
+                            tableRelations.push(`    ${quote(relationKey)}: one(${targetTableVar}, {\n        relationName: ${quote(drizzleRelationName)}\n    })`);
                             break;
 
                         case "hasMany":
-                            tableRelations.push(`    "${relationKey}": many(${targetTableVar}, { relationName: \"${drizzleRelationName}\" })`);
+                            tableRelations.push(`    ${quote(relationKey)}: many(${targetTableVar}, { relationName: ${quote(drizzleRelationName)} })`);
                             break;
 
                         case "manyToMany": {
@@ -874,7 +886,7 @@ export const generateSchema = async (allCollections: CollectionConfig[], stripPo
                             // junction table — unnecessary now that each side names
                             // its own.
                             const junctionTableVar = getTableVarName(rel.through.table);
-                            tableRelations.push(`    "${relationKey}": many(${junctionTableVar}, { relationName: \"${drizzleRelationName}\" })`);
+                            tableRelations.push(`    ${quote(relationKey)}: many(${junctionTableVar}, { relationName: ${quote(drizzleRelationName)} })`);
                             break;
                         }
 

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

@@ -2,7 +2,6 @@ import { promises as fsPromises } from "fs";
 import * as fs from "fs";
 import path from "path";
 import { pathToFileURL } from "url";
-import chokidar from "chokidar";
 import { generateSchema } from "./generate-drizzle-schema-logic";
 import { CollectionConfig } from "@rebasepro/types";
 import { loadCollectionsFromDirectory } from "@rebasepro/server";
@@ -93,7 +92,7 @@ const runGeneration = async (collectionsFilePath?: string, outputPath?: string)
     }
 };
 
-const main = () => {
+const main = async () => {
     const collectionsFilePathArg = process.argv.find(arg => arg.startsWith("--collections="));
     const collectionsFilePath = collectionsFilePathArg ? collectionsFilePathArg.split("=")[1] : process.argv[2];
 
@@ -112,6 +111,18 @@ const main = () => {
 
     if (watch) {
         out(`Watching for changes in ${resolvedPath}...`);
+        // Imported here rather than at module scope, and this is not a style
+        // choice: chokidar is needed only by `--watch`, which is a
+        // schema-authoring path that never runs inside the runtime image. A
+        // top-level import puts it on the boot path of the published driver
+        // bundle, and the image installs a hand-listed set of runtime
+        // dependencies that does not include it — so the whole driver failed to
+        // load with "Cannot find package 'chokidar'", and every self-hosted
+        // container answered 500 with a stack trace about a file watcher.
+        //
+        // Same reasoning the image already applies to @ariga/atlas: an
+        // authoring-only dependency does not belong on a boot path.
+        const { default: chokidar } = await import("chokidar");
         const watcher = chokidar.watch(resolvedPath, {
             persistent: true,
             ignoreInitial: false

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

@@ -20,6 +20,7 @@ import {
     vectorIndexStatements,
     type VectorIndexPlan
 } from "./vector-index";
+import { buildCollectionIndexSpecs, collectionIndexStatements } from "./collection-index";
 import { REBASE_SCHEMA } from "@rebasepro/types";
 
 // --- Helper Functions ---
@@ -734,7 +735,14 @@ export const generatePostgresDdl = async (
                 indexStatements.push(`-- No ANN index on "${skip.schema}"."${skip.table}"."${skip.column}": ${skip.reason}`);
             }
 
-            // Backwards compatibility: add default id primary key if missing
+            // The collection's own `indexes:` block. Last of the three index
+            // producers, and the only one the developer wrote deliberately
+            // rather than getting as a side effect of another feature.
+            indexStatements.push(...collectionIndexStatements(
+                buildCollectionIndexSpecs(collection, resolveColumnName)
+            ));
+
+            // The implicit primary key, for a collection that declares none.
             const hasPk = columns.some(c => c.includes("PRIMARY KEY"));
             if (!hasPk) {
                 columns.unshift('  "id" TEXT PRIMARY KEY');
@@ -762,16 +770,20 @@ export const generatePostgresDdl = async (
         }
     }
 
-    if (fkStatements.length > 0) {
-        ddl += "-- Foreign Key Constraints\n";
-        ddl += fkStatements.join("\n") + "\n\n";
-    }
-
+    // Indexes before foreign keys. Today every FK targets a primary key created
+    // inline, so the order is safe by accident; the moment a declared
+    // `unique: true` index can back an FK target, a constraint emitted first
+    // would reference an index that does not exist yet.
     if (indexStatements.length > 0) {
         ddl += "-- Indexes\n";
         ddl += indexStatements.join("\n") + "\n\n";
     }
 
+    if (fkStatements.length > 0) {
+        ddl += "-- Foreign Key Constraints\n";
+        ddl += fkStatements.join("\n") + "\n\n";
+    }
+
     if (policyStatements.length > 0) {
         ddl += "-- Row Level Security Policies\n";
         ddl += policyStatements.join("");

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

@@ -2,7 +2,6 @@ import { promises as fsPromises } from "fs";
 import * as fs from "fs";
 import path from "path";
 import { pathToFileURL } from "url";
-import chokidar from "chokidar";
 import {
     generatePostgresDdl,
     generatePostgresPoliciesDdl,
@@ -77,7 +76,7 @@ const runGeneration = async (collectionsFilePath?: string, outputPath?: string)
     }
 };
 
-const main = () => {
+const main = async () => {
     const collectionsFilePathArg = process.argv.find(arg => arg.startsWith("--collections="));
     const collectionsFilePath = collectionsFilePathArg ? collectionsFilePathArg.split("=")[1] : process.argv[2];
 
@@ -96,6 +95,18 @@ const main = () => {
 
     if (watch) {
         out(`Watching for changes in ${resolvedPath}...`);
+        // Imported here rather than at module scope, and this is not a style
+        // choice: chokidar is needed only by `--watch`, which is a
+        // schema-authoring path that never runs inside the runtime image. A
+        // top-level import puts it on the boot path of the published driver
+        // bundle, and the image installs a hand-listed set of runtime
+        // dependencies that does not include it — so the whole driver failed to
+        // load with "Cannot find package 'chokidar'", and every self-hosted
+        // container answered 500 with a stack trace about a file watcher.
+        //
+        // Same reasoning the image already applies to @ariga/atlas: an
+        // authoring-only dependency does not belong on a boot path.
+        const { default: chokidar } = await import("chokidar");
         const watcher = chokidar.watch(resolvedPath, {
             persistent: true,
             ignoreInitial: false