@rebasepro/server-postgres 0.13.0 → 0.13.1-canary.g249daa1

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

@@ -1,6 +1,19 @@
 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, resolveStringColumnLength } from "@rebasepro/common";
-import { toSnakeCase, getPolicyNamesForRule, generateForeignKeyName, legacyForeignKeyName } 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, toPostgresIdentifier } from "@rebasepro/utils";
+import { AUTH_USERS_COLUMNS, authUsersColumnDefinition, authUsersColumnSql, isAuthCollection } from "./auth-users-columns";
+import {
+    buildSearchColumnSpec,
+    searchColumnDefinition,
+    fuzzyColumnDefinition,
+    searchIndexStatements,
+    searchHelperFunctions,
+    searchExtensionStatements,
+    searchColumnNames,
+    searchIndexNames,
+    type SearchColumnSpec
+} from "./search-column";
+import { REBASE_SCHEMA } from "@rebasepro/types";
 
 // --- Helper Functions ---
 
@@ -235,15 +248,138 @@ export const getSqlColumnType = (propName: string, prop: Property, collection: C
     }
 };
 
+/**
+ * Everything a `search` block needs, as a file Rebase applies itself.
+ *
+ * Search is the one part of the schema Atlas does not own. Two independent
+ * reasons, and either alone would be enough:
+ *
+ * 1. Its free tier refuses to *parse* a desired-state file that so much as
+ *    contains a function — "functions and procedures are available to
+ *    logged-in users only". A generated `tsvector` column cannot avoid one:
+ *    `unaccent` is STABLE and jsonb flattening needs a set-returning function,
+ *    so both have to be wrapped in an IMMUTABLE helper to be legal in a
+ *    generated column at all.
+ * 2. Even with the file accepted, Atlas *wipes* the dev database it diffs
+ *    against, so a helper seeded there beforehand is gone by the time the plan
+ *    is analysed. There is no hook to reinstate it.
+ *
+ * So the column, its index and its helpers are excluded from Atlas's view
+ * (`searchExcludePatterns`) and applied from here — the same arrangement the
+ * RLS policies already use, and for the same underlying reason.
+ *
+ * Ordered as it must run: extensions, then helpers, then the column whose
+ * expression calls them, then the index over that column. Every statement is
+ * `IF NOT EXISTS` / `OR REPLACE`, because this is replayed on every push and
+ * appended to migrations that run against databases at any stage of their
+ * life. Empty when nothing opted in — the caller writes no file then.
+ *
+ * The leading half — extensions and helpers, without the table-shaped
+ * statements — is available on its own as {@link searchPrerequisiteStatements},
+ * for the dev database Atlas analyses plans against. That database has none of
+ * the project's tables, so it wants the functions and nothing else.
+ */
+export const searchPrerequisiteStatements = (allCollections: CollectionConfig[]): string[] => {
+    const specs = relationalCollections(allCollections)
+        .map(c => buildSearchColumnSpec(c))
+        .filter((s): s is SearchColumnSpec => s !== undefined);
+    if (specs.length === 0) return [];
+    return [
+        ...new Set(specs.flatMap(searchExtensionStatements)),
+        ...new Set(specs.flatMap(searchHelperFunctions))
+    ];
+};
+
+export const generatePostgresSearchDdl = (allCollections: CollectionConfig[]): string => {
+    const collections = relationalCollections(allCollections);
+    const specs = collections
+        .map(c => buildSearchColumnSpec(c))
+        .filter((s): s is SearchColumnSpec => s !== undefined);
+    if (specs.length === 0) return "";
+
+    const extensions = Array.from(new Set(specs.flatMap(searchExtensionStatements)));
+    const helpers = Array.from(new Set(specs.flatMap(searchHelperFunctions)));
+
+    let ddl = "-- This file is auto-generated by the Rebase DDL generator. Do not edit manually.\n";
+    ddl += "--\n";
+    ddl += "-- Full-text search for the collections declaring a `search` block.\n";
+    ddl += "-- Applied by Rebase, not by Atlas — see generatePostgresSearchDdl.\n\n";
+
+    extensions.forEach(s => { ddl += `${s}\n`; });
+    if (extensions.length > 0) ddl += "\n";
+    helpers.forEach(s => { ddl += `${s}\n\n`; });
+
+    for (const collection of collections) {
+        const spec = buildSearchColumnSpec(collection);
+        if (!spec) continue;
+        const schema = isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
+        const table = `"${schema}"."${getTableName(collection)}"`;
+
+        // ADD COLUMN IF NOT EXISTS rather than the inline definition the
+        // CREATE TABLE would use: by the time this runs the table exists,
+        // whether Atlas just created it or it has been live for a year.
+        ddl += `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS ${searchColumnDefinition(spec)};\n`;
+        const fuzzyDef = fuzzyColumnDefinition(spec);
+        if (fuzzyDef) ddl += `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS ${fuzzyDef};\n`;
+        searchIndexStatements(spec).forEach(s => { ddl += `${s}\n`; });
+        ddl += "\n";
+    }
+
+    return ddl;
+};
+
+/**
+ * Glob patterns telling Atlas to leave the search column and its index alone.
+ *
+ * Without these, a desired state that omits search reads to Atlas as an
+ * instruction to drop the column — taking the index and the whole search
+ * feature with it on the next push.
+ *
+ * Fully qualified, `schema.table.object`, matching the include list. The
+ * two-part form is what Atlas wants when the connection URL scopes it to one
+ * schema and is *silently ignored* otherwise: it reads `posts.search_vector`
+ * as a table named `search_vector` in a schema named `posts`, matches nothing,
+ * and reports no error for the pattern that never fired.
+ */
+export const searchExcludePatterns = (allCollections: CollectionConfig[]): string[] => {
+    const patterns: string[] = [];
+    for (const collection of relationalCollections(allCollections)) {
+        const spec = buildSearchColumnSpec(collection);
+        if (!spec) continue;
+        const schema = isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
+        const table = getTableName(collection);
+        for (const name of searchColumnNames(collection)) {
+            patterns.push(`${schema}.${table}.${name}`);
+        }
+        for (const index of searchIndexNames(spec)) {
+            patterns.push(`${schema}.${table}.${index}`);
+        }
+    }
+    return patterns;
+};
+
 export const generatePostgresDdl = async (
-    collections: CollectionConfig[],
-    options: { includePolicies?: boolean } = { includePolicies: true }
+    allCollections: CollectionConfig[],
+    options: { includePolicies?: boolean; includeSearch?: boolean } = {
+        includePolicies: true,
+        includeSearch: 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 => {
@@ -251,6 +387,32 @@ export const generatePostgresDdl = async (
     });
     if (uniqueSchemas.length > 0) ddl += "\n";
 
+    // 1b. Search support, for collections that opted in.
+    //
+    // Extensions and helper functions come before every CREATE TABLE because a
+    // generated column's expression is resolved at creation time: a table whose
+    // search column calls `rebase_search_text` cannot be created before that
+    // function exists. Both are `IF NOT EXISTS` / `OR REPLACE`, so a file
+    // replayed against a live database is a no-op here.
+    const searchSpecs = collections
+        .map(c => buildSearchColumnSpec(c))
+        .filter((s): s is SearchColumnSpec => s !== undefined);
+
+    if (searchSpecs.length > 0) {
+        if (options.includeSearch === false) {
+            // Everything search-related lives in `search.sql` — see
+            // `generatePostgresSearchDdl` for why Atlas is not shown any of it.
+            ddl += "-- Full-text search support lives in `search.sql`, applied separately.\n\n";
+        } else {
+            const extensions = Array.from(new Set(searchSpecs.flatMap(searchExtensionStatements)));
+            const helpers = Array.from(new Set(searchSpecs.flatMap(searchHelperFunctions)));
+            ddl += "-- Full-text search support (collections declaring a `search` block)\n";
+            extensions.forEach(s => { ddl += `${s}\n`; });
+            if (extensions.length > 0) ddl += "\n";
+            helpers.forEach(s => { ddl += `${s}\n\n`; });
+        }
+    }
+
     // 2. Generate Enums
     //
     // The enum type name is derived from table + column, so two collections
@@ -318,6 +480,9 @@ export const generatePostgresDdl = async (
 
     // 3. Generate tables
     const fkStatements: string[] = [];
+    // Indexes follow the tables for the same reason the FK constraints do: the
+    // table has to exist first.
+    const indexStatements: string[] = [];
     // Policies are emitted after every CREATE TABLE, like the FK constraints:
     // a policy may reference other tables (a junction's derived policies always
     // reference both endpoints; `policy.existsIn` references a join table), and
@@ -355,8 +520,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
@@ -414,7 +579,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);
@@ -436,10 +601,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}`;
 
@@ -476,6 +658,40 @@ 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)}`);
+                }
+            }
+
+            // ── The opt-in search column ─────────────────────────────────────
+            // Last, so it reads as what it is: derived from the columns above
+            // it. Postgres recomputes it on every write of a source column and
+            // rejects any attempt to write it directly, which is the property
+            // that makes it impossible for the index to drift from the row.
+            const searchSpec = options.includeSearch === false ? undefined : buildSearchColumnSpec(collection);
+            if (searchSpec) {
+                columns.push(`  ${searchColumnDefinition(searchSpec)}`);
+                const fuzzyDef = fuzzyColumnDefinition(searchSpec);
+                if (fuzzyDef) columns.push(`  ${fuzzyDef}`);
+                indexStatements.push(...searchIndexStatements(searchSpec));
+            }
+
             // Backwards compatibility: add default id primary key if missing
             const hasPk = columns.some(c => c.includes("PRIMARY KEY"));
             if (!hasPk) {
@@ -509,6 +725,11 @@ export const generatePostgresDdl = async (
         ddl += fkStatements.join("\n") + "\n\n";
     }
 
+    if (indexStatements.length > 0) {
+        ddl += "-- Indexes\n";
+        ddl += indexStatements.join("\n") + "\n\n";
+    }
+
     if (policyStatements.length > 0) {
         ddl += "-- Row Level Security Policies\n";
         ddl += policyStatements.join("");
@@ -575,10 +796,31 @@ const schemaOfCollection = (collection: CollectionConfig): string =>
 
 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)`.
+ */
+// Moved to `@rebasepro/utils` so the search-column builder derives index names
+// under the same 63-byte rule this file derives constraint names under. Two
+// copies of a truncation rule is two rules the moment one of them is edited.
+
 const foreignKeyPlan = (
     args: Omit<ForeignKeyPlan, "constraintName" | "sql"> & { onDelete: string; onUpdate?: string }
 ): ForeignKeyPlan => {
-    const constraintName = `${args.table}_${args.column}_fkey`;
+    const constraintName = toPostgresIdentifier(`${args.table}_${args.column}_fkey`);
     const onUpdate = args.onUpdate ? ` ON UPDATE ${args.onUpdate.toUpperCase()}` : "";
     return {
         constraintName,
@@ -610,7 +852,8 @@ const foreignKeyPlan = (
  * 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[] => {
+export const planRelationalColumns = (allCollections: CollectionConfig[]): RelationalColumnPlan[] => {
+    const collections = relationalCollections(allCollections);
     const plans: RelationalColumnPlan[] = [];
 
     for (const collection of collections) {
@@ -703,7 +946,8 @@ export const planRelationalColumns = (collections: CollectionConfig[]): Relation
  * 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[] => {
+export const planJunctionTables = (allCollections: CollectionConfig[]): JunctionTablePlan[] => {
+    const collections = relationalCollections(allCollections);
     const plans: JunctionTablePlan[] = [];
 
     for (const spec of resolveJunctionSpecs(collections).values()) {
@@ -780,7 +1024,10 @@ export interface CollectionPolicyPlan {
  * 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[] => {
+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>();
@@ -833,7 +1080,11 @@ export const planCollectionPolicies = (collections: CollectionConfig[]): Collect
     return plans;
 };
 
-export const generatePostgresPoliciesDdl = (collections: CollectionConfig[]): string => {
+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, {

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

@@ -3,7 +3,11 @@ import * as fs from "fs";
 import path from "path";
 import { pathToFileURL } from "url";
 import chokidar from "chokidar";
-import { generatePostgresDdl, generatePostgresPoliciesDdl } from "./generate-postgres-ddl-logic";
+import {
+    generatePostgresDdl,
+    generatePostgresPoliciesDdl,
+    generatePostgresSearchDdl
+} from "./generate-postgres-ddl-logic";
 import { CollectionConfig } from "@rebasepro/types";
 import { logger, loadCollectionsFromDirectory } from "@rebasepro/server";
 
@@ -29,8 +33,16 @@ const runGeneration = async (collectionsFilePath?: string, outputPath?: string)
         // Sort collections by slug alphabetically to ensure deterministic DDL generation
         collections.sort((a, b) => a.slug.localeCompare(b.slug));
 
-        const ddlContent = await generatePostgresDdl(collections, { includePolicies: false });
+        // `schema.sql` is Atlas's desired state, and it carries neither the RLS
+        // policies nor the search apparatus: Atlas manages neither, and in the
+        // search case cannot. Both are written beside it and applied by the CLI
+        // in their own right.
+        const ddlContent = await generatePostgresDdl(collections, {
+            includePolicies: false,
+            includeSearch: false
+        });
         const policiesContent = generatePostgresPoliciesDdl(collections);
+        const searchContent = generatePostgresSearchDdl(collections);
 
         if (outputPath) {
             const outputDir = path.dirname(outputPath);
@@ -41,6 +53,17 @@ const runGeneration = async (collectionsFilePath?: string, outputPath?: string)
             const policiesPath = path.join(outputDir, "policies.sql");
             await fsPromises.writeFile(policiesPath, policiesContent);
             logger.info(`✅ PostgreSQL Policies DDL generated successfully at ${policiesPath}`);
+
+            // Removed when the last `search` block goes: the CLI applies this
+            // file whenever it exists, and a stale one would keep re-creating
+            // functions for collections that no longer want them.
+            const searchPath = path.join(outputDir, "search.sql");
+            if (searchContent) {
+                await fsPromises.writeFile(searchPath, searchContent);
+                logger.info(`✅ PostgreSQL search DDL generated successfully at ${searchPath}`);
+            } else if (fs.existsSync(searchPath)) {
+                await fsPromises.rm(searchPath);
+            }
         } else {
             logger.info("✅ PostgreSQL DDL generated successfully.");
             logger.info(String(ddlContent));

package/src/schema/generated-schema-staleness.ts

@@ -0,0 +1,169 @@
+import { CollectionConfig } from "@rebasepro/types";
+import { getTableName, resolveCollectionRelations, relationalCollections } from "@rebasepro/common";
+import { generateForeignKeyName, legacyForeignKeyName } from "@rebasepro/utils";
+
+/**
+ * Notice a generated Drizzle schema that a *library upgrade* invalidated.
+ *
+ * `rebase dev` already watches `config/collections` and warns when a collection
+ * file changes. That covers drift the developer caused. It cannot cover this one,
+ * because nothing the developer owns changed: 0.13 derives `category_id` where
+ * 0.12 derived `categorie_id`, from the same unedited collection. The watcher
+ * never fires, and `backend/src/schema.generated.ts` quietly stops describing the
+ * schema the runtime expects.
+ *
+ * The consequence is not cosmetic. Boot-ensure renames the column in the
+ * database, then relation validation reads the stale module and refuses to
+ * start — on that boot and every boot after it, because the rename is already
+ * applied and will not be attempted again.
+ *
+ * Deliberately narrow: this answers "does the generated schema name a foreign key
+ * the way the previous rule did", not "is this file what we would generate now".
+ * The wide question would report every whitespace change in the generator as a
+ * fatal staleness, and a check that cries wolf gets switched off.
+ */
+
+/** One column the generated schema names under the pre-0.13 rule. */
+export interface LegacyForeignKeyName {
+    /** Table whose column declaration is stale. */
+    table: string;
+    /** The name the generated schema declares. */
+    legacy: string;
+    /** The name this release derives, and which the database now carries. */
+    current: string;
+    /** `<collection>.<relation>` that derives it, for the message. */
+    relation: string;
+}
+
+/**
+ * The slice of the generated source declaring one table.
+ *
+ * Scoping matters: two junctions in one file can carry columns of the same name,
+ * and a whole-file match would attribute a stale column to whichever table the
+ * reader looks at first. Returns "" when the table is not in the file at all,
+ * which is not staleness — it is a table the generator has not been asked about.
+ */
+function tableBlock(source: string, table: string): string {
+    const start = source.indexOf(`pgTable("${table}"`);
+    if (start === -1) return "";
+    // Generated files put every table in its own `export const`, so the next one
+    // is the end of this block. No brace counting, nothing to get wrong.
+    const next = source.indexOf("\nexport ", start);
+    return next === -1 ? source.slice(start) : source.slice(start, next);
+}
+
+/**
+ * Whether a block *declares* the column, rather than merely mentioning it.
+ *
+ * A comment explaining the rename, or a policy expression naming the old column,
+ * must not read as a declaration — otherwise regenerating the file would not
+ * clear the finding and the check would be permanently red.
+ */
+function declaresColumn(block: string, column: string): boolean {
+    // `categorie_id: integer("categorie_id")` — the Drizzle column shape. The key
+    // and the string argument agree in generated output, so requiring both is
+    // both precise and cheap.
+    const key = column.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[\\s,{])${key}\\s*:\\s*\\w+\\(\\s*["']${key}["']`, "m").test(block);
+}
+
+/**
+ * @param generatedSource contents of `backend/src/schema.generated.ts`
+ * @param collections     the project's collections, as this release reads them
+ */
+export function findLegacyForeignKeyNames(
+    generatedSource: string,
+    collections: CollectionConfig[]
+): LegacyForeignKeyName[] {
+    const found: LegacyForeignKeyName[] = [];
+    const seen = new Set<string>();
+
+    /**
+     * Report `wanted` as stale when the generated schema declares what the
+     * previous rule would have derived from `source` instead.
+     *
+     * The `wanted !== current` guard is what honours an explicitly named column.
+     * An author who pinned `categorie_id` has said so on the relation, so the
+     * generated file agreeing with them is correct, not stale — and the rename
+     * note documents exactly that opt-out.
+     */
+    const consider = (
+        table: string,
+        wanted: string,
+        sourceName: string | undefined,
+        relation: string
+    ): void => {
+        if (!table || !wanted || !sourceName) return;
+
+        const current = generateForeignKeyName(sourceName);
+        const legacy = legacyForeignKeyName(sourceName);
+        if (legacy === current) return;   // this name never moved
+        if (wanted !== current) return;   // pinned by the author, or unrelated
+
+        const block = tableBlock(generatedSource, table);
+        if (!block) return;
+        if (!declaresColumn(block, legacy)) return;
+        if (declaresColumn(block, current)) return;   // already regenerated
+
+        const key = `${table}.${legacy}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        found.push({ table, legacy, current, relation });
+    };
+
+    // Same rule as the generator whose output this reads: a collection that
+    // gets no table cannot have named a column in it. Inert in practice today —
+    // the finding also requires the generated file to declare the table — but
+    // the guard is what keeps that true when a non-SQL collection's slug happens
+    // to match a SQL one's table.
+    for (const collection of relationalCollections(collections)) {
+        const sourceTable = getTableName(collection);
+
+        for (const [name, relation] of Object.entries(resolveCollectionRelations(collection))) {
+            const at = `${collection.slug}.${name}`;
+
+            let target: CollectionConfig | undefined;
+            try {
+                target = relation.target?.();
+            } catch {
+                // A throwing target thunk is its own defect, reported at boot by
+                // `validate-relations`. Nothing to say about its column names.
+                continue;
+            }
+
+            switch (relation.kind) {
+                case "belongsTo":
+                    consider(sourceTable, relation.localKey, relation.relationName, at);
+                    break;
+
+                case "hasOne":
+                case "hasMany":
+                    if (target) {
+                        consider(getTableName(target), relation.foreignKeyOnTarget, collection.slug, at);
+                    }
+                    break;
+
+                case "manyToMany":
+                    consider(relation.through.table, relation.through.sourceColumn, collection.slug, at);
+                    if (target) {
+                        consider(relation.through.table, relation.through.targetColumn, target.slug, at);
+                    }
+                    break;
+
+                default:
+                    // `via` joins are written by hand — there is no derived name
+                    // for the rule change to have moved.
+                    break;
+            }
+        }
+    }
+
+    return found;
+}
+
+/** One-line summary for a log or a CLI notice. */
+export function describeLegacyForeignKeyNames(found: LegacyForeignKeyName[]): string {
+    return found
+        .map(f => `  • ${f.table}.${f.legacy} → ${f.current}  (${f.relation})`)
+        .join("\n");
+}

package/src/schema/introspect-db-logic.ts

@@ -1089,7 +1089,7 @@ export function generateCollectionFile(
 
         if (derivedFacts) {
             const titleProperty = deriveTitleProperty(derivedFacts);
-            if (titleProperty) adminEntries.push(`titleProperty: ${quote(titleProperty)}`);
+            if (titleProperty) adminEntries.push(`display: { title: ${quote(titleProperty)} }`);
 
             const kanbanProperty = deriveKanbanProperty(derivedFacts);
             if (kanbanProperty) adminEntries.push(`kanban: {\n            columnProperty: ${quote(kanbanProperty)}\n        }`);