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

package/src/cli.ts

@@ -5,18 +5,21 @@ import path from "path";
 import fs from "fs";
 import { fileURLToPath } from "url";
 import { logger } from "@rebasepro/server";
+import { formatRelativeTime } from "@rebasepro/utils";
 import {
+    diagnoseMissingBin,
     resolveLocalBin,
     getTableIncludes,
     getDevDatabaseUrl,
     ensureDevDatabaseExists,
     getTableExcludes,
-    ExcludeIntrospectionError
+    ExcludeIntrospectionError,
+    promptConfirm
 } from "./cli-helpers";
 import { checkDatabaseConnectivity, diagnoseDbError } from "./cli-errors";
-import { AUTH_BOOTSTRAP_SQL } from "./schema/auth-bootstrap-sql";
+import { forLibpq } from "./utils/connection-string";
+import { dropLegacyAuthSchema, RLS_BOOTSTRAP_SQL } from "./schema/rls-bootstrap-sql";
 import { detectDestructiveStatements, decidePushSafety } from "./schema/destructive-sql";
-import readline from "readline";
 
 const __cliDirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -136,14 +139,14 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
                     );
                     fs.writeFileSync(newestMigrationFile, migrationContent, "utf-8");
 
-                    // Append RLS policies, preceded by the auth bootstrap so the
+                    // Append RLS policies, preceded by the RLS bootstrap so the
                     // migration is self-contained: Atlas replays migrations
-                    // against a clean dev database where `auth.uid()` would not
-                    // otherwise exist.
+                    // against a clean dev database where `rebase.uid()` would
+                    // not otherwise exist.
                     const policiesFile = path.resolve(process.cwd(), "drizzle", "policies.sql");
                     if (fs.existsSync(policiesFile)) {
                         const policiesContent = fs.readFileSync(policiesFile, "utf-8");
-                        fs.appendFileSync(newestMigrationFile, "\n\n" + AUTH_BOOTSTRAP_SQL + "\n" + policiesContent);
+                        fs.appendFileSync(newestMigrationFile, "\n\n" + RLS_BOOTSTRAP_SQL + "\n" + policiesContent);
                         logger.info(chalk.gray(`  ✓ Appended RLS policies to migration file: ${path.basename(newestMigrationFile)}`));
                         
                         // Re-hash the migration directory
@@ -234,6 +237,7 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
                 await applyPolicies(databaseUrl);
                 await reconcilePolicies(databaseUrl, collectionsPath);
                 await ensureRlsUserRole(databaseUrl);
+                await retireLegacyAuthSchema(databaseUrl);
             } else {
                 logger.warn(chalk.yellow("  ⚠️  DATABASE_URL not found in environment, skipping RLS policies application."));
             }
@@ -246,6 +250,7 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
             await runAtlas("migrate", ["apply", "--dir", "file://drizzle/migrations", ...extraArgs], collectionsPath);
             if (databaseUrl) {
                 await ensureRlsUserRole(databaseUrl);
+                await retireLegacyAuthSchema(databaseUrl);
             }
         }
 
@@ -261,16 +266,20 @@ async function ensureAuthSchemaAndFunctions(databaseUrl: string): Promise<void>
         const client = new Client({ connectionString: databaseUrl });
         await client.connect();
         try {
-            await client.query(AUTH_BOOTSTRAP_SQL);
-            // Runtime-only: pre-create the schema Atlas uses for its revision
-            // table (`--revisions-schema rebase`). Kept out of
-            // AUTH_BOOTSTRAP_SQL so it never enters the migration stream.
-            await client.query("CREATE SCHEMA IF NOT EXISTS rebase");
+            // Creates the `rebase` schema as its first statement, which also
+            // covers the schema Atlas puts its revision table in
+            // (`--revisions-schema rebase`). That used to need a separate,
+            // deliberately migration-stream-excluded statement here, because the
+            // helper functions lived in `auth` and creating `rebase` from the
+            // preamble would have made Atlas plan a DROP for it. The generator
+            // now always declares `rebase` in the desired schema, so there is
+            // nothing to keep out.
+            await client.query(RLS_BOOTSTRAP_SQL);
         } finally {
             await client.end();
         }
     } catch (err) {
-        logger.warn(chalk.yellow(`  ⚠️  Failed to bootstrap auth schema and helper functions: ${err instanceof Error ? err.message : String(err)}`));
+        logger.warn(chalk.yellow(`  ⚠️  Failed to bootstrap the RLS helper functions: ${err instanceof Error ? err.message : String(err)}`));
     }
 }
 
@@ -318,19 +327,82 @@ async function ensureAuthTables(databaseUrl: string, collectionsPath: string): P
  * connection would bypass RLS (superuser / BYPASSRLS / table owner).
  */
 async function ensureRlsUserRole(databaseUrl: string): Promise<void> {
-    const { detectConnectionPosture, ensureAppRole, REBASE_USER_ROLE } = await import("./security/rls-enforcement");
-    const { Client } = await import("pg");
-    const client = new Client({ connectionString: databaseUrl });
-    await client.connect();
+    // Every failure in here used to escape uncaught, and `db migrate`'s caller
+    // turns that into a bare `process.exit(1)` — so the migration would apply,
+    // print `-- ok`, and then the command would die with NO output whatsoever
+    // and a non-zero status. Seen with a module-resolution error inside the
+    // dynamic import, where the entire diagnosis was one silent exit code.
+    //
+    // Reported rather than rethrown, and deliberately not fatal: the schema
+    // change has already landed at this point, so failing the command implies a
+    // rollback that did not happen. What is actually lost is the role
+    // provisioning, and the message says so and how to finish it by hand.
+    // No `auth`: the RLS helpers live in `rebase` now, and a schema the
+    // framework no longer creates must not be granted on — on a Supabase
+    // database that would hand the end-user role USAGE on their auth schema.
+    const schemas = ["public", "rebase"];
+    let rls: typeof import("./security/rls-enforcement");
     try {
-        const runSql = async (text: string) => (await client.query(text)).rows as Record<string, unknown>[];
-        const posture = await detectConnectionPosture(runSql);
-        if (posture.privileged) {
-            await ensureAppRole(runSql, ["public", "rebase", "auth"]);
-            logger.info(chalk.gray(`  ✓ RLS role "${REBASE_USER_ROLE}" provisioned/refreshed.`));
+        rls = await import("./security/rls-enforcement");
+    } catch (err) {
+        // A module-resolution failure here is a build problem, not a database
+        // one, and it is exactly the case that used to produce the silent exit.
+        logger.error(chalk.red(
+            `\n  ✗ Could not load the RLS provisioning module: ${err instanceof Error ? err.message : String(err)}`
+        ));
+        return;
+    }
+
+    try {
+        const { Client } = await import("pg");
+        const client = new Client({ connectionString: databaseUrl });
+        await client.connect();
+        try {
+            const runSql = async (text: string) => (await client.query(text)).rows as Record<string, unknown>[];
+            const posture = await rls.detectConnectionPosture(runSql);
+            if (posture.privileged) {
+                await rls.ensureAppRole(runSql, schemas);
+                logger.info(chalk.gray(`  ✓ RLS role "${rls.REBASE_USER_ROLE}" provisioned/refreshed.`));
+            }
+        } finally {
+            await client.end();
         }
-    } finally {
-        await client.end();
+    } catch (err) {
+        logger.error(chalk.red(
+            `\n  ✗ The schema change was applied, but the "${rls.REBASE_USER_ROLE}" role could not be ` +
+            `provisioned: ${err instanceof Error ? err.message : String(err)}`
+        ));
+        logger.error(chalk.gray(rls.appRoleSetupInstructions("your database user", schemas)));
+    }
+}
+
+/**
+ * Retire the pre-1.0 `auth` schema, once nothing depends on it any more.
+ *
+ * Runs last on purpose. Postgres refuses to drop a function an RLS policy still
+ * calls, so this only succeeds after the policies above have been rewritten to
+ * `rebase.uid()`. See `dropLegacyAuthSchema` for what it reports when something
+ * hand-written is still holding the schema open, and DROP_LEGACY_AUTH_SCHEMA_SQL
+ * for the guards that keep it off a Supabase `auth` schema.
+ */
+async function retireLegacyAuthSchema(databaseUrl: string): Promise<void> {
+    try {
+        const { Client } = await import("pg");
+        const client = new Client({ connectionString: databaseUrl });
+        await client.connect();
+        try {
+            await dropLegacyAuthSchema(
+                async (text) => (await client.query(text)).rows as Record<string, unknown>[],
+                {
+                    info: (m) => logger.info(chalk.gray(`  ${m}`)),
+                    warn: (m) => logger.warn(chalk.yellow(`  ⚠️  ${m}`))
+                }
+            );
+        } finally {
+            await client.end();
+        }
+    } catch {
+        // Connection-level failure only; the schema is inert either way.
     }
 }
 
@@ -597,36 +669,15 @@ function formatBytes(bytes: number): string {
     return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
 }
 
+/** A branch's age, for "…created 6d ago". */
 function timeAgo(date: Date): string {
-    const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
-    if (seconds < 60) return "just now";
-    const minutes = Math.floor(seconds / 60);
-    if (minutes < 60) return `${minutes}m ago`;
-    const hours = Math.floor(minutes / 60);
-    if (hours < 24) return `${hours}h ago`;
-    const days = Math.floor(hours / 24);
-    return `${days}d ago`;
+    // No horizon: a branch created a year ago should still report an age here,
+    // rather than fall back to a bare date in a one-line list entry.
+    return formatRelativeTime(date, { maxMs: Number.POSITIVE_INFINITY }) ?? "unknown";
 }
 
 
 
-/**
- * Ask a yes/no question on an interactive terminal. Non-interactive shells
- * (CI, pipes, agents) can't answer, so this must only be reached after
- * {@link decidePushSafety} has already ruled that interactive confirmation is
- * possible.
- */
-async function promptConfirm(question: string): Promise<boolean> {
-    if (!process.stdin.isTTY) return false;
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    try {
-        const answer: string = await new Promise((resolve) => rl.question(question, resolve));
-        return /^y(es)?$/i.test(answer.trim());
-    } finally {
-        rl.close();
-    }
-}
-
 async function runAtlas(
     domain: "schema" | "migrate",
     args: string[],
@@ -635,9 +686,36 @@ async function runAtlas(
 ): Promise<string> {
     const atlasBin = resolveLocalBin("atlas");
     if (!atlasBin) {
-        logger.error(chalk.red("✗ Could not find atlas binary."));
-        const installCmd = "pnpm add -D @ariga/atlas";
-        logger.error(chalk.gray(`  Install it with: ${installCmd}`));
+        // Two very different causes, and the advice for one is a loop for the
+        // other — see `diagnoseMissingBin`. This used to say "Install it with:
+        // pnpm add -D @ariga/atlas" unconditionally, which is the exact command
+        // that produces the far more common of the two states.
+        logger.error(chalk.red("\n✗ The atlas binary is missing, so the schema cannot be applied.\n"));
+
+        if (diagnoseMissingBin("@ariga/atlas") === "build-script-blocked") {
+            logger.error(chalk.yellow("  @ariga/atlas IS installed — only its binary is missing.\n"));
+            logger.error(chalk.gray(
+                "  It downloads that binary in a `preinstall` script, and pnpm 10+ does not\n" +
+                "  run a dependency's scripts unless you allow it. The install still exits 0,\n" +
+                "  so the only sign is `Ignored build scripts: @ariga/atlas` in its output.\n"
+            ));
+            logger.error("  Fix it with either:\n");
+            logger.error(chalk.bold("    pnpm approve-builds\n"));
+            logger.error("  or, to record it in the project (what `rebase init` scaffolds):\n");
+            logger.error(chalk.bold(
+                "    // package.json\n" +
+                "    \"pnpm\": { \"onlyBuiltDependencies\": [\"@ariga/atlas\"] }\n"
+            ));
+            logger.error(chalk.gray("  Then re-run `pnpm install`.\n"));
+        } else {
+            logger.error(chalk.gray("  It is not installed in this project.\n"));
+            logger.error("  Install it with:\n");
+            logger.error(chalk.bold("    pnpm add -D @ariga/atlas\n"));
+            logger.error(chalk.gray(
+                "  If pnpm then reports `Ignored build scripts`, also run `pnpm approve-builds` —\n" +
+                "  the package carries a `preinstall` script that fetches the binary.\n"
+            ));
+        }
         process.exit(1);
     }
 
@@ -682,19 +760,25 @@ async function runAtlas(
     const devDatabaseUrl = getDevDatabaseUrl(databaseUrl);
     await ensureDevDatabaseExists(databaseUrl, devDatabaseUrl);
 
+    // Atlas speaks libpq, which rejects the `sslmode=no-verify` that
+    // node-postgres accepts — see `forLibpq`. Rewritten only for the argv, so
+    // everything above still connects with the URL as configured.
+    const atlasUrl = forLibpq(databaseUrl);
+    const atlasDevUrl = forLibpq(devDatabaseUrl);
+
     const atlasArgs = [domain, ...args];
 
     if (domain === "schema") {
         if (args.includes("apply")) {
-            atlasArgs.push("--url", databaseUrl, "--dev-url", devDatabaseUrl);
+            atlasArgs.push("--url", atlasUrl, "--dev-url", atlasDevUrl);
         } else if (args.includes("clean") || args.includes("inspect")) {
-            atlasArgs.push("--url", databaseUrl);
+            atlasArgs.push("--url", atlasUrl);
         }
     } else if (domain === "migrate") {
         if (args.includes("diff")) {
-            atlasArgs.push("--dev-url", devDatabaseUrl);
+            atlasArgs.push("--dev-url", atlasDevUrl);
         } else if (args.includes("apply") || args.includes("status")) {
-            atlasArgs.push("--url", databaseUrl, "--revisions-schema", "rebase");
+            atlasArgs.push("--url", atlasUrl, "--revisions-schema", "rebase");
             if (args.includes("apply")) {
                 atlasArgs.push("--allow-dirty");
             }
@@ -810,7 +894,86 @@ async function generatePostgresDdlCommand(rawArgs: string[]): Promise<void> {
     }
 }
 
+/**
+ * `schema stale [--fix]` — is the generated Drizzle schema older than the rule
+ * that derives its foreign-key names?
+ *
+ * This exists for one upgrade path and is worth the command. 0.13 derives
+ * `category_id` where 0.12 derived `categorie_id`; boot-ensure renames the
+ * database column to match, and the project's checked-in
+ * `backend/src/schema.generated.ts` is then wrong in a way nothing the developer
+ * did would explain. Relation validation refuses to boot on it, permanently,
+ * because the rename has already been applied and will not run again.
+ *
+ * `rebase dev` calls this with `--fix` before starting the backend, so the
+ * upgrade behaves the way the release note says it does: the column moves and the
+ * project keeps working. Without `--fix` it reports and exits non-zero, which is
+ * what a build or a CI step wants.
+ */
+async function schemaStaleCommand(rawArgs: string[]): Promise<void> {
+    const argsList = arg(
+        {
+            "--collections": String,
+            "--output": String,
+            "--fix": Boolean,
+            "-c": "--collections",
+            "-o": "--output"
+        },
+        { argv: rawArgs.slice(2), permissive: true }
+    );
+
+    const collectionsPath = argsList["--collections"] || path.join("..", "config", "collections");
+    const outputPath = argsList["--output"] || path.join("src", "schema.generated.ts");
+    const schemaFile = path.resolve(process.cwd(), outputPath);
+
+    // No generated schema yet is not staleness — a fresh project has not run the
+    // generator, and saying "stale" about a file that does not exist would send
+    // the reader looking for something to fix.
+    if (!fs.existsSync(schemaFile)) return;
+
+    const { loadCollections } = await import("./schema/doctor");
+    const { findLegacyForeignKeyNames, describeLegacyForeignKeyNames } =
+        await import("./schema/generated-schema-staleness");
+
+    let stale;
+    try {
+        const collections = await loadCollections(path.resolve(process.cwd(), collectionsPath));
+        stale = findLegacyForeignKeyNames(fs.readFileSync(schemaFile, "utf8"), collections);
+    } catch (err) {
+        // Best-effort by design: a collections directory that will not load is a
+        // real error, but it is one the boot reports far better than this does.
+        logger.debug(`schema stale: skipped (${err instanceof Error ? err.message : String(err)})`);
+        return;
+    }
+
+    if (stale.length === 0) return;
+
+    logger.info("");
+    logger.warn(chalk.yellow(
+        `  ⚠️  ${outputPath} names ${stale.length} foreign key(s) the way an earlier release did:`
+    ));
+    logger.info(chalk.gray(describeLegacyForeignKeyNames(stale)));
+    logger.info("");
+
+    if (!argsList["--fix"]) {
+        logger.error(chalk.red(
+            "  The database column has already been renamed at boot, so the generated schema no " +
+            "longer matches it and the server will refuse to start."
+        ));
+        logger.error(chalk.red("  Run `rebase schema generate` to regenerate it."));
+        process.exit(1);
+    }
+
+    logger.info(chalk.gray("  Regenerating the Drizzle schema so it matches..."));
+    await schemaCommand("generate", ["schema", "generate", `--collections=${collectionsPath}`, `--output=${outputPath}`]);
+}
+
 async function schemaCommand(subcommand: string, rawArgs: string[]): Promise<void> {
+    if (subcommand === "stale") {
+        await schemaStaleCommand(rawArgs);
+        return;
+    }
+
     if (subcommand === "generate") {
         const argsList = arg(
             {

package/src/collections/validate-relations.ts

@@ -2,6 +2,7 @@ import { getTableColumns } from "drizzle-orm";
 import { PgTable } from "drizzle-orm/pg-core";
 import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
 import { getTableName, resolveCollectionRelations } from "@rebasepro/common";
+import { generateForeignKeyName, legacyForeignKeyName } from "@rebasepro/utils";
 
 import { PostgresCollectionRegistry } from "./PostgresCollectionRegistry";
 
@@ -58,6 +59,68 @@ const quote = (xs: Iterable<string>) => Array.from(xs).map(s => `\`${s}\``).join
 /** `on.from` / `on.to` accept a single column or a composite tuple. */
 const asColumns = (value: string | string[]): string[] => Array.isArray(value) ? value : [value];
 
+/**
+ * Distinguish "this column name is wrong" from "the generated schema is old".
+ *
+ * They present identically here — a relation asks for a column the registered
+ * table does not have — but they are opposite problems with opposite fixes, and
+ * getting them the wrong way round is how the 0.12 → 0.13 upgrade bricked
+ * projects.
+ *
+ * The registered table is not the database. It comes from the project's
+ * checked-in `backend/src/schema.generated.ts`, and 0.13 changed the rule that
+ * derives foreign-key names: `categories` yields `category_id` where it used to
+ * yield `categorie_id`. Boot-ensure renames the database column to match, so by
+ * the time this runs the *database* is correct and the *generated module* is the
+ * stale one. Reporting "not a column" then points at the wrong artifact, and the
+ * generic fix — "set `through.targetColumn` to one of: …", listing the legacy
+ * name because that is what the stale module still has — talks the reader into
+ * pinning a column that no longer exists.
+ *
+ * So when the wanted name is what the current rule derives, and the table
+ * carries what the *previous* rule would have derived from the same source, say
+ * that instead.
+ *
+ * @param wanted   the column the relation asks for
+ * @param available every column the registered table has
+ * @param sources  names the default could have been derived from (a slug, a
+ *                 relation name) — checking against these rather than guessing
+ *                 backwards from `wanted` keeps the match exact
+ */
+function staleCodegenRename(
+    wanted: string,
+    available: Set<string>,
+    sources: string[]
+): { legacy: string; current: string } | null {
+    for (const source of sources) {
+        if (!source) continue;
+        const current = generateForeignKeyName(source);
+        const legacy = legacyForeignKeyName(source);
+        // Only a name that actually moved, and only when the table still has the
+        // old spelling and not the new one.
+        if (current !== wanted || legacy === current) continue;
+        if (available.has(legacy) && !available.has(current)) return { legacy, current };
+    }
+    return null;
+}
+
+/** The shared explanation, so every relation kind reports it identically. */
+function staleCodegenDefect(
+    table: string,
+    { legacy, current }: { legacy: string; current: string }
+): Pick<RelationDefect, "problem" | "fix"> {
+    return {
+        problem:
+            `the generated Drizzle schema still declares \`${legacy}\` on \`${table}\`, but this ` +
+            `release derives \`${current}\` — the generated schema predates the foreign-key ` +
+            "naming fix and no longer describes the database",
+        fix:
+            "regenerate it with `rebase schema generate` (or `pnpm run schema:generate`). The " +
+            "database column has already been renamed for you at boot, so nothing else is needed. " +
+            `To keep \`${legacy}\` instead, name it explicitly on the relation and regenerate.`
+    };
+}
+
 /**
  * Relations whose names do not resolve against the registered schema.
  *
@@ -117,11 +180,20 @@ kind: relation.kind };
             switch (relation.kind) {
                 case "belongsTo": {
                     if (!sourceColumns.has(relation.localKey)) {
-                        defects.push({
-                            ...at,
-                            problem: `\`localKey: "${relation.localKey}"\` is not a column on \`${sourceTableName}\``,
-                            fix: `add the column, or set \`localKey\` to one of: ${quote(sourceColumns)}`
-                        });
+                        // `localKey` defaults to the relation name run through
+                        // the foreign-key rule, so it moves with that rule.
+                        const stale = staleCodegenRename(
+                            relation.localKey,
+                            sourceColumns,
+                            [relation.relationName, targetCollection.slug]
+                        );
+                        defects.push(stale
+                            ? { ...at, ...staleCodegenDefect(sourceTableName, stale) }
+                            : {
+                                ...at,
+                                problem: `\`localKey: "${relation.localKey}"\` is not a column on \`${sourceTableName}\``,
+                                fix: `add the column, or set \`localKey\` to one of: ${quote(sourceColumns)}`
+                            });
                     }
                     break;
                 }
@@ -129,10 +201,34 @@ kind: relation.kind };
                 case "hasOne":
                 case "hasMany": {
                     if (!targetColumns.has(relation.foreignKeyOnTarget)) {
+                        // The default is derived from *this* collection's slug —
+                        // the column on the target that points back here.
+                        const stale = staleCodegenRename(
+                            relation.foreignKeyOnTarget,
+                            targetColumns,
+                            [collection.slug]
+                        );
+                        defects.push(stale
+                            ? { ...at, ...staleCodegenDefect(targetTableName, stale) }
+                            : {
+                                ...at,
+                                problem: `\`foreignKeyOnTarget: "${relation.foreignKeyOnTarget}"\` is not a column on the target table \`${targetTableName}\``,
+                                fix: `add the column, or set \`foreignKeyOnTarget\` to one of: ${quote(targetColumns)}`
+                            });
+                    }
+                    // `sourceKey` is the easiest of the two to put on the wrong
+                    // side — it is the only column in a `hasMany` that lives
+                    // here rather than on the target, and naming a target column
+                    // reads perfectly well right next to `foreignKeyOnTarget`.
+                    if (relation.sourceKey && !sourceColumns.has(relation.sourceKey)) {
                         defects.push({
                             ...at,
-                            problem: `\`foreignKeyOnTarget: "${relation.foreignKeyOnTarget}"\` is not a column on the target table \`${targetTableName}\``,
-                            fix: `add the column, or set \`foreignKeyOnTarget\` to one of: ${quote(targetColumns)}`
+                            problem: `\`sourceKey: "${relation.sourceKey}"\` is not a column on \`${sourceTableName}\``,
+                            fix: targetColumns.has(relation.sourceKey)
+                                ? `it is a column on the *target* table \`${targetTableName}\` — \`sourceKey\` names ` +
+                                  "the column on this collection that the target's foreign key points at, so it " +
+                                  `must be one of: ${quote(sourceColumns)}`
+                                : `add the column, or set \`sourceKey\` to one of: ${quote(sourceColumns)}`
                         });
                     }
                     break;
@@ -152,14 +248,24 @@ kind: relation.kind };
                         break;
                     }
                     const junctionColumns = columnNames(junction);
+                    // Junction columns are the ones that actually moved in 0.13:
+                    // each defaults to its endpoint collection's *slug* run
+                    // through the foreign-key rule, and slugs are plural.
+                    const derivedFrom = {
+                        sourceColumn: [collection.slug],
+                        targetColumn: [targetCollection.slug]
+                    } as const;
                     for (const [label, column] of [["sourceColumn", sourceColumn], ["targetColumn", targetColumn]] as const) {
                         if (!junctionColumns.has(column)) {
-                            defects.push({
-                                ...at,
-                                problem: `\`through.${label}: "${column}"\` is not a column on the junction table \`${table}\``,
-                                fix: `set \`through.${label}\` to one of: ${quote(junctionColumns)}` +
-                                    (label === "sourceColumn" ? " — it is the column naming *this* collection" : "")
-                            });
+                            const stale = staleCodegenRename(column, junctionColumns, [...derivedFrom[label]]);
+                            defects.push(stale
+                                ? { ...at, ...staleCodegenDefect(table, stale) }
+                                : {
+                                    ...at,
+                                    problem: `\`through.${label}: "${column}"\` is not a column on the junction table \`${table}\``,
+                                    fix: `set \`through.${label}\` to one of: ${quote(junctionColumns)}` +
+                                        (label === "sourceColumn" ? " — it is the column naming *this* collection" : "")
+                                });
                         }
                     }
                     break;
@@ -272,9 +378,25 @@ export function assertRelationsResolve(
     );
 
     throw new Error(
-        `${defects.length} relation${defects.length === 1 ? "" : "s"} cannot resolve against the database schema.\n\n` +
+        `${defects.length} relation${defects.length === 1 ? "" : "s"} cannot resolve against ` +
+        "`backend/src/schema.generated.ts`.\n\n" +
         "Each of these would return no rows at query time rather than reporting an error, " +
         "so they are fatal at boot instead.\n\n" +
+        // This reads the *generated file*, not the database, and the difference
+        // is the whole diagnosis after an upgrade. Boot-ensure renames columns
+        // in the database — a 0.12 → 0.13 upgrade singularises a junction key,
+        // `categorie_id` → `category_id` — and the checked-in file still
+        // declares the old name. The config is then correct and the file is
+        // stale, so the per-defect advice below, which lists the columns this
+        // file has, names a column that no longer exists in the database.
+        // Following it turns a recoverable state into a broken config.
+        //
+        // Hence the ordering: regenerate first, and only then consider that the
+        // collection might be the thing that is wrong.
+        "If the database was migrated recently — an upgrade, a `db push`, a restore — this file is\n" +
+        "probably older than the schema it describes. Regenerate it before changing anything else:\n\n" +
+        "    rebase schema generate\n\n" +
+        "If it is already current, then the collection is what disagrees with it:\n\n" +
         lines.join("\n\n") + "\n"
     );
 }