@zerotal/orm 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -8,6 +8,94 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.11.0] — 2026-08-31
+
+### Changed
+
+- **BREAKING: SQLite enforces foreign keys.** `database.sqlite.foreignKeys` now
+  defaults to `true`, so `PRAGMA foreign_keys = ON` is set on every connection.
+  Until now SQLite ignored them, which made `constrained()` and `cascadeOnDelete()`
+  in a migration a statement of intent the database would not perform — deleting a
+  parent left its children, silently, and an app's data-erasure path missed three
+  tables because of it.
+
+  **What can break:** a child row whose parent is missing was legal without
+  enforcement and is a violation with it, so a write touching one now fails. Run
+  `zt db:check-foreign-keys` before deploying — it lists every offending row by table
+  and rowid and exits non-zero, so a release script can gate on it. `zt doctor`
+  reports the same. To take the release without dealing with it yet, set
+  `sqlite: { foreignKeys: false }`, and remove the override afterwards; with it in
+  place `cascadeOnDelete()` does nothing. See
+  [the upgrade guide](/docs/upgrade#1-10-to-1-11).
+
+- **BREAKING: a renumbered migration is refused rather than re-run.** A migration is
+  recorded under its filename, so renaming one makes an applied migration look
+  pending — the runner tried it again and failed on `table already exists`, which is a
+  failed boot with an error naming a table rather than the rename. An app renumbered
+  `001_` to `0001_` to match this framework's own scaffold convention and would have
+  made all nine of its production migrations look unrun.
+
+  `migrate` now recognises a pending migration whose name matches a recorded one once
+  the leading digits are stripped, and stops with both spellings and the fix. It
+  refuses rather than warns because the alternative is running it, and running it is
+  the outage.
+
+### Added
+
+- **`Migration.id`** — a declared identity that decouples a migration from its
+  filename. Set it to what the database already recorded and the file is free to be
+  renamed. Deliberately not a content hash: a migration's content is edited far more
+  often than its name, and a hash would make every edit look like a new migration.
+
+- **`zt db:check-foreign-keys`** — lists the rows enforcement would reject, by table
+  and rowid, and exits non-zero when there are any.
+
+### Changed
+
+- **`@column({ type: "integer" })` compiles.** `ColumnShorthand` has twelve names and
+  `ColumnOptions["type"]` had six, so `@column("integer")` worked and
+  `@column({ type: "integer", default: 0 })` did not — the vocabulary shrank by half
+  exactly when a caller needed `default`, `nullable` or `unique`, which is most real
+  columns. The error listed the six without mentioning that `integer` resolves to
+  `{ type: "number", cast: "integer" }`, so the way out was reading `SHORTHAND_MAP` in
+  the source.
+
+  The object form now takes either vocabulary and resolves a shorthand the way the
+  string form does. An explicit `cast` alongside one still wins: somebody who wrote
+  both meant the one they spelled out.
+
+### Fixed
+
+- **Migration names no longer carry the platform that recorded them.** `Bun.Glob`
+  yields native separators, and the prefix strip was a forward-slash-only pattern —
+  so on Windows the whole joined path went into the `migrations` table. An app found
+  `database\migrations\010_add_tenant_limits` in ten dev rows and
+  `010_add_tenant_limits` in production, from the same files.
+
+  A database moved between the two re-runs every migration: every recorded name
+  misses, all of them look pending, and the first fails on `table already exists` —
+  a failed boot, not a graceful skip. The name is now the bare filename on both.
+
+  Note the half this does _not_ fix: the recorded identity is still the filename, so
+  renaming a migration makes it look unrun. The same app nearly took an outage
+  renumbering `001_` to `0001_` to match this framework's own scaffold convention.
+
+### Added
+
+- **`database.sqlite.foreignKeys`**, and a `zt doctor` check for the schemas that
+  need it. **SQLite ignores foreign keys unless the connection asks it not to**, so
+  `constrained()` and `cascadeOnDelete()` in a migration described behaviour the
+  database would not perform: deleting a parent left its children, silently, and
+  every child had to be removed by hand in the right order by code that remembered
+  to. An app's data-erasure path swept fifteen tables and missed three — including
+  both holding uploaded files — so an erasure left the paperwork on disk.
+
+  Off by default, because turning it on can fail writes an existing database already
+  permits: a row whose parent is missing is legal without enforcement and a violation
+  with it. Run `PRAGMA foreign_key_check` before enabling on an existing database. The
+  doctor check warns only when the schema actually declares a foreign key, so an app
+  with none hears nothing.
+
 ## [1.9.0] — 2026-08-29
 
 ### Changed

package/api-surface.md

@@ -287,6 +287,7 @@ class JsonCast = {
 
 class Migration = {
   new (): Migration
+  static id?: string
   down: () => Promise<void>
   up: () => Promise<void>
 }
@@ -838,7 +839,7 @@ interface DatabaseConfigShape = {
   driver: 'sqlite' | 'postgres' | 'mysql'
   pool?: {    max?: number;    idleTimeout?: number;} | undefined
   replicas?: string[] | undefined
-  sqlite: {    path: string;}
+  sqlite: {    path: string;    foreignKeys?: boolean | undefined;}
   synchronize?: boolean | {    enabled: boolean;    disruptive?: boolean;} | undefined
   url: string
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -31,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.10.0",
-    "@zerotal/validator": "1.10.0"
+    "@zerotal/core": "1.11.0",
+    "@zerotal/validator": "1.11.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/commands/CheckForeignKeysCommand.ts

@@ -0,0 +1,80 @@
+import { Command } from "@zerotal/core";
+import { _getConnection } from "../db/DB.ts";
+
+/** One row `PRAGMA foreign_key_check` objects to. */
+interface Violation {
+  table: string;
+  rowid: number | null;
+  parent: string;
+  fkid: number;
+}
+
+/**
+ * `bun zt db:check-foreign-keys` — list the rows enforcement would reject.
+ *
+ * SQLite ignores foreign keys unless the connection asks it not to, and Zerotal now
+ * asks by default. That is the right default — a `cascadeOnDelete()` the database
+ * will not perform is worse than no cascade at all — but it changes what an
+ * *existing* database accepts: a child row whose parent is missing is perfectly legal
+ * without enforcement and a constraint violation with it. So an app that has been
+ * running without it may already hold rows that a write will now fail on.
+ *
+ * This is how you find out before your users do. It reports every offending row by
+ * table and rowid, and exits non-zero when there are any, so a deploy script can gate
+ * on it.
+ *
+ * @example
+ * ```bash
+ * # before taking the upgrade, or any time after
+ * bun zt db:check-foreign-keys
+ * ```
+ *
+ * @category Database
+ */
+export class CheckForeignKeysCommand extends Command {
+  static override commandName = "db:check-foreign-keys";
+  static override description = "List rows that violate a foreign key constraint";
+  static override needsApp = true;
+
+  async run(): Promise<void> {
+    const sql = _getConnection();
+
+    let violations: Violation[];
+    try {
+      violations = await sql<Violation>`PRAGMA foreign_key_check`;
+    } catch (error) {
+      // Postgres and MySQL always enforce, so they have no such pragma and nothing
+      // to report. Saying that is more useful than an error about syntax.
+      this.info(
+        `No foreign-key check to run on this driver — only SQLite can have enforcement off. ` +
+          `(${(error as Error).message})`,
+      );
+      return;
+    }
+
+    if (violations.length === 0) {
+      this.info("No foreign-key violations. Enforcement is safe to leave on.");
+      return;
+    }
+
+    this.error(`${violations.length} row(s) violate a foreign key:`);
+    this.newLine();
+    this.table(
+      violations.map((v) => [
+        `${v.table} rowid ${v.rowid ?? "?"}`,
+        `references ${v.parent}, which has no matching row`,
+      ]) as [string, string][],
+    );
+    this.newLine();
+    this.line(
+      "Each of these is a row whose parent is missing. With enforcement on, a write\n" +
+        "touching one fails. Delete them, or repoint them at a parent that exists.\n\n" +
+        "To keep deploying while you sort it out, set sqlite.foreignKeys: false in\n" +
+        "config/database.ts — and take the override back off afterwards, because with\n" +
+        "it in place cascadeOnDelete() does nothing.",
+    );
+
+    // Non-zero so a release script can gate on this the way it gates on tests.
+    process.exitCode = 1;
+  }
+}

package/src/commands/_loadMigrations.ts

@@ -26,9 +26,40 @@ export async function loadMigrations(): Promise<MigrationRecord[]> {
     const mod = await import(`${process.cwd()}/${file}`);
     const Ctor = mod.default as (new () => MigrationRecord["instance"]) | undefined;
     if (!Ctor) continue;
-    const name = file.replace(/^database\/migrations\//, "").replace(/\.ts$/, "");
-    records.push({ name, instance: new Ctor() });
+    // A declared `static id` wins over the filename — see `Migration.id`.
+    const declared = (Ctor as { id?: string }).id;
+    records.push({ name: declared ?? _migrationName(file), instance: new Ctor() });
   }
 
   return records;
 }
+
+/**
+ * The identity a migration is recorded under: its bare filename, no directory, no
+ * extension, no platform in it.
+ *
+ * `Bun.Glob` yields native separators, so on Windows this receives
+ * `database\migrations\010_x.ts`. The prefix used to be stripped with a
+ * forward-slash-only pattern, which matched nothing there — and the value written
+ * into the `migrations` table was the whole joined path, backslashes and all.
+ *
+ * Two ways that hurts, and the second is the dangerous one:
+ *
+ * - **A database moved between platforms re-runs every migration.** Every recorded
+ *   name misses, all of them look pending, and the first one fails on `table
+ *   already exists`. That is a failed boot rather than a graceful skip.
+ * - **The recorded name is compared against the file's**, so anything that changes
+ *   the string makes a migration look unrun. An app renumbered `001_` to `0001_` to
+ *   match this framework's own scaffold convention and nearly took an outage: nine
+ *   applied migrations would have looked pending. Normalising the separator does not
+ *   fix that half — a rename is still a new identity — but it stops the *platform*
+ *   from being part of the string, which is the half nobody can see coming.
+ *
+ * @param file - Path as the glob yielded it, relative to the project root.
+ * @returns The bare migration name.
+ * @internal
+ */
+export function _migrationName(file: string): string {
+  const normalised = file.split("\\").join("/");
+  return (normalised.split("/").at(-1) ?? normalised).replace(/\.[cm]?[jt]s$/, "");
+}

package/src/config.ts

@@ -45,6 +45,34 @@ export interface DatabaseConfigShape {
   sqlite: {
     /** Path to the SQLite file. Use ':memory:' for in-memory database. */
     path: string;
+    /**
+     * Enforce foreign keys on every SQLite connection (`PRAGMA foreign_keys = ON`).
+     *
+     * **SQLite ignores foreign keys unless you ask it not to**, and it is the only
+     * supported dialect that does. Without this, `cascadeOnDelete()` and
+     * `constrained()` in a migration are a statement of intent that the database
+     * will not perform: deleting a parent leaves its children behind, and every
+     * child has to be deleted by hand, in the right order, by application code that
+     * remembers to.
+     *
+     * That is not a theoretical cost. An app's data-erasure path swept fifteen
+     * tables and missed three — including both tables holding uploaded files — so an
+     * account erasure left the paperwork on disk and its rows in the database. They
+     * found it by having a second person write the runbook and compare the prose
+     * against the code.
+     *
+     * **On by default**, because an API describing behaviour the database will not
+     * perform is the worst of the available states — worse than not offering it.
+     *
+     * Set it to `false` for an existing database that may already hold rows a
+     * constraint would reject: a child whose parent is missing is legal without
+     * enforcement and a violation with it, so turning it on can fail a write the app
+     * has always made. `zt db:check-foreign-keys` lists exactly those rows, and
+     * `zt doctor` reports them too. Fix them, then remove the override.
+     *
+     * Default: `true`. Postgres and MySQL always enforce, so this is ignored there.
+     */
+    foreignKeys?: boolean | undefined;
   };
   /**
    * Auto-sync the schema to your models at boot (TypeORM-style). Opt-in, and
@@ -66,7 +94,7 @@ export interface DatabaseConfigShape {
 const defaults: DatabaseConfigShape = {
   driver: "sqlite",
   url: "./database/db.sqlite",
-  sqlite: { path: "./database/db.sqlite" },
+  sqlite: { path: "./database/db.sqlite", foreignKeys: true },
 };
 
 /**

package/src/doctor/foreignKeys.ts

@@ -0,0 +1,130 @@
+/**
+ * The check for a migration that promises a cascade the database will not perform.
+ *
+ * SQLite ignores foreign keys unless the connection asks it not to, and it is the
+ * only supported dialect that does. So a migration reading
+ *
+ * ```ts
+ * table.foreignId("transaction_id").constrained("transactions").cascadeOnDelete();
+ * ```
+ *
+ * describes behaviour that does not happen: deleting a parent leaves its children,
+ * and every child has to be removed by hand, in the right order, by application code
+ * that remembers to. Nothing errors. Nothing logs. The declaration reads like a
+ * guarantee and is a comment.
+ *
+ * An app's data-erasure path swept fifteen tables and missed three, including both
+ * that held uploaded files — so an account erasure left the paperwork on disk and its
+ * rows in the database. That is a compliance failure produced by an API that reads
+ * like a promise, which is why this warns rather than staying quiet: an API
+ * describing behaviour the database will not perform is worse than either turning it
+ * on or not offering it.
+ *
+ * @module
+ */
+import type { Application } from "@zerotal/core";
+import type { DoctorCheck, DoctorCheckResult } from "@zerotal/core";
+import type { SQLInstance } from "../db/sql-types.ts";
+
+/** Whether this connection enforces foreign keys right now. */
+async function _enforcing(sql: SQLInstance): Promise<boolean | null> {
+  try {
+    const rows = (await sql`PRAGMA foreign_keys`) as { foreign_keys?: number }[];
+    const value = rows[0]?.foreign_keys;
+    return value === undefined ? null : Number(value) === 1;
+  } catch {
+    return null;
+  }
+}
+
+/** Tables that declare at least one foreign key, so the promise is actually being made. */
+async function _tablesWithForeignKeys(sql: SQLInstance): Promise<number> {
+  try {
+    const rows = (await sql`
+      SELECT COUNT(*) AS n
+      FROM sqlite_master AS m
+      WHERE m.type = 'table'
+        AND m.sql LIKE '%REFERENCES%'
+    `) as { n?: number }[];
+    return Number(rows[0]?.n ?? 0);
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Report a schema that declares foreign keys on a connection that ignores them.
+ *
+ * Silent when the app declares none — plenty of schemas legitimately have no
+ * constraints, and warning about an unused setting is how a doctor becomes noise.
+ */
+export const foreignKeysCheck: DoctorCheck = {
+  id: "sqlite-foreign-keys",
+  label: "Foreign keys",
+  async run(app: Application): Promise<DoctorCheckResult> {
+    let driver = "sqlite";
+    let sql: SQLInstance | undefined;
+    try {
+      const config = app.container.makeSync("config") as { get<T>(k: string, d: T): T };
+      driver = config.get<string>("database.driver", "sqlite");
+      sql = app.container.makeSync("db") as SQLInstance;
+    } catch {
+      return { status: "ok", message: "no database connection to check" };
+    }
+
+    // Postgres and MySQL always enforce; there is nothing to get wrong.
+    if (driver !== "sqlite") return { status: "ok", message: `${driver} enforces them` };
+    if (!sql) return { status: "ok", message: "no database connection to check" };
+
+    const enforcing = await _enforcing(sql);
+    if (enforcing === null) return { status: "ok", message: "could not read the pragma" };
+
+    // Enforced: the remaining question is whether the data already agrees. A row whose
+    // parent is missing was legal before enforcement and is a violation now, so an
+    // upgraded database can carry rows that the next write touching them will fail on.
+    if (enforcing) {
+      const violations = await _violationCount(sql);
+      if (violations === 0) return { status: "ok", message: "enforced, and the data agrees" };
+      return {
+        status: "fail",
+        message:
+          `Foreign keys are enforced and ${violations} row(s) already violate one — rows whose ` +
+          `parent is missing, which were legal before enforcement and are not now. A write ` +
+          `touching one of them fails.`,
+        fix:
+          "Run `zt db:check-foreign-keys` to see them by table and rowid. Delete them or " +
+          "repoint them at a parent that exists. To keep deploying meanwhile, set " +
+          "sqlite.foreignKeys: false in config/database.ts — and take it back off after, " +
+          "because with it in place cascadeOnDelete() does nothing.",
+      };
+    }
+
+    const declaring = await _tablesWithForeignKeys(sql);
+    if (declaring === 0) {
+      return { status: "ok", message: "not enforced, and nothing declares one" };
+    }
+
+    return {
+      status: "warn",
+      message:
+        `${declaring} table(s) declare a foreign key, and this SQLite connection does not ` +
+        `enforce them — so \`constrained()\` and \`cascadeOnDelete()\` in your migrations ` +
+        `describe behaviour the database will not perform. Deleting a parent leaves its ` +
+        `children, silently.`,
+      fix:
+        "Set database.sqlite.foreignKeys: true in config/database.ts. On an existing " +
+        "database, run `PRAGMA foreign_key_check` first — enforcement turns an already-" +
+        "orphaned row into a write that fails.",
+    };
+  },
+};
+
+/** How many rows violate a foreign key right now. `0` when the pragma is unavailable. */
+async function _violationCount(sql: SQLInstance): Promise<number> {
+  try {
+    const rows = (await sql`PRAGMA foreign_key_check`) as unknown[];
+    return rows.length;
+  } catch {
+    return 0;
+  }
+}

package/src/model/decorators/column.ts

@@ -82,6 +82,9 @@ export interface ColumnOptions {
    *
    * @default "string"
    */
+  // Spelled out rather than written as {@link ColumnStorageType}: this line is the
+  // recorded public surface, and replacing a union with an alias of identical members
+  // reads as a removal in the diff even though nothing changed.
   type?: "string" | "text" | "number" | "boolean" | "datetime" | "json" | undefined;
   /** Mark this column as the table's primary key. */
   primary?: boolean | undefined;
@@ -143,6 +146,28 @@ export interface ColumnOptions {
 /**
  * Map each ColumnShorthand to its resolved ColumnOptions.
  */
+/**
+ * The types a column is actually *stored* as — what schema generation emits.
+ *
+ * Distinct from {@link ColumnShorthand}, which is the larger vocabulary a caller may
+ * write. `integer`, `float`, `date` and the encrypted forms are shorthands that
+ * resolve to one of these plus a cast.
+ */
+export type ColumnStorageType = "string" | "text" | "number" | "boolean" | "datetime" | "json";
+
+/**
+ * What `@column({ … })` accepts, as opposed to what it resolves to.
+ *
+ * The difference is `type`: a caller may write any {@link ColumnShorthand} there and
+ * it is resolved to a storage type plus a cast, exactly as the string form is.
+ * {@link ColumnOptions} — the resolved shape held in metadata and read back by
+ * schema generation — keeps the narrow storage union, because widening a property
+ * people *read* breaks the ones who assigned it to the narrower type.
+ */
+export type ColumnOptionsInput = Omit<ColumnOptions, "type"> & {
+  type?: ColumnStorageType | ColumnShorthand | undefined;
+};
+
 const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
   string: { type: "string" },
   text: { type: "text" },
@@ -170,7 +195,7 @@ const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
  * `Omit<ColumnOptions, "type">`, so it cannot contradict the type it is modifying.
  */
 function resolveOptions(
-  arg?: ColumnShorthand | ColumnOptions,
+  arg?: ColumnShorthand | ColumnOptionsInput,
   extra?: Omit<ColumnOptions, "type">,
 ): ColumnOptions {
   const base = _resolveBase(arg);
@@ -184,7 +209,7 @@ function resolveOptions(
   return merged;
 }
 
-function _resolveBase(arg?: ColumnShorthand | ColumnOptions): ColumnOptions {
+function _resolveBase(arg?: ColumnShorthand | ColumnOptionsInput): ColumnOptions {
   if (arg === undefined) return { type: "string" };
   if (typeof arg === "string") {
     const a = arg as string;
@@ -197,7 +222,36 @@ function _resolveBase(arg?: ColumnShorthand | ColumnOptions): ColumnOptions {
       } as ColumnOptions;
     return SHORTHAND_MAP[a as ColumnShorthand] ?? { type: "string" };
   }
-  return arg;
+  return _resolveOptionType(arg);
+}
+
+/**
+ * Let the object form take a shorthand `type`, resolving it the way the string form
+ * would.
+ *
+ * `@column("integer")` compiled and `@column({ type: "integer", default: 0 })` did
+ * not — so the vocabulary shrank from twelve names to six exactly when a caller
+ * needed `default`, `nullable` or `unique`, which is most real columns. And the
+ * error listed the six without mentioning that `integer` means
+ * `{ type: "number", cast: "integer" }`, so the way out was reading this file.
+ *
+ * An explicit `cast` wins over the shorthand's own: someone who wrote both meant the
+ * one they spelled out.
+ *
+ * @param options - The options object as written.
+ * @returns The same options with any shorthand `type` resolved to storage type + cast.
+ */
+function _resolveOptionType(options: ColumnOptionsInput): ColumnOptions {
+  const declared = options.type;
+  if (declared === undefined) return options as ColumnOptions;
+
+  const shorthand = SHORTHAND_MAP[declared as ColumnShorthand];
+  // A storage type maps to itself with no cast — `string`, `text`, `number`,
+  // `boolean`, `datetime` and `json` appear in both vocabularies and mean the same
+  // thing in each, so there is nothing to resolve.
+  if (!shorthand || shorthand.type === declared) return options as ColumnOptions;
+
+  return { ...shorthand, ...options, type: shorthand.type };
 }
 
 // ── Reactivity ────────────────────────────────────────────────────────────────
@@ -308,7 +362,7 @@ export function column(
   options: Omit<ColumnOptions, "type">,
 ): ColumnDecorator;
 export function column(
-  arg?: ColumnShorthand | ColumnOptions,
+  arg?: ColumnShorthand | ColumnOptionsInput,
   extra?: Omit<ColumnOptions, "type">,
 ): ColumnDecorator {
   const options = resolveOptions(arg, extra);

package/src/provider/DatabaseProvider.ts

@@ -5,6 +5,7 @@ import type { ConfigManager } from "@zerotal/core/config";
 import { SQL } from "bun";
 import { DB, _getConnection } from "../db/DB.ts";
 import { preventNPlusOne } from "../db/NPlusOneDetector.ts";
+import { foreignKeysCheck } from "../doctor/foreignKeys.ts";
 import {
   _setBaseModelConnection,
   _setBaseModelDialect,
@@ -118,6 +119,10 @@ export class DatabaseProvider extends ServiceProvider {
         pool?.max !== undefined || pool?.idleTimeout !== undefined ? { url, ...pool } : url;
       const primary = new SQL(sqlArg as unknown as string);
 
+      const driver = config.get<string>("database.driver", "sqlite");
+      const enforceForeignKeys = config.get<boolean>("database.sqlite.foreignKeys", true);
+      await _applySqlitePragmas(primary, driver, enforceForeignKeys);
+
       if (replicaUrls.length === 0) return primary;
 
       // Build read replicas and wrap in a transparent read/write router.
@@ -131,6 +136,9 @@ export class DatabaseProvider extends ServiceProvider {
             : replicaUrl;
         return new SQL(replicaSqlArg as unknown as string);
       });
+      for (const replica of replicas) {
+        await _applySqlitePragmas(replica, driver, enforceForeignKeys);
+      }
 
       return createReadWriteRouter(primary, replicas);
     });
@@ -214,7 +222,7 @@ export class DatabaseProvider extends ServiceProvider {
    * it — `doctor` already boots the app and already holds the connection.
    */
   override doctorChecks(): DoctorCheck[] {
-    return [pendingMigrationsCheck];
+    return [pendingMigrationsCheck, foreignKeysCheck];
   }
 
   override async onBooted(): Promise<void> {
@@ -252,6 +260,9 @@ export class DatabaseProvider extends ServiceProvider {
     runner.registerLazy("migrate:refresh", () =>
       import("../commands/MigrateRefreshCommand.ts").then((m) => m.MigrateRefreshCommand),
     );
+    runner.registerLazy("db:check-foreign-keys", () =>
+      import("../commands/CheckForeignKeysCommand.ts").then((m) => m.CheckForeignKeysCommand),
+    );
     runner.registerLazy("migrate:status", () =>
       import("../commands/MigrateStatusCommand.ts").then((m) => m.MigrateStatusCommand),
     );
@@ -323,3 +334,29 @@ function _detectDialect(raw: string): "sqlite" | "postgres" | "mysql" {
   if (raw.startsWith("mysql://") || raw.startsWith("mysql2://")) return "mysql";
   return "sqlite";
 }
+
+/**
+ * Apply the connection-scoped PRAGMAs SQLite needs, if this is SQLite.
+ *
+ * `foreign_keys` is **per connection**, not per database, so it has to be set on
+ * every handle the app opens — including each read replica. Setting it once on the
+ * primary and assuming it stuck is how this ends up half-enforced.
+ *
+ * @param sql - The connection to configure.
+ * @param driver - The configured driver; anything but `sqlite` is left alone.
+ * @param foreignKeys - Whether to enforce foreign keys on this connection.
+ * @internal
+ */
+export async function _applySqlitePragmas(
+  sql: SQLInstance,
+  driver: string,
+  foreignKeys: boolean,
+): Promise<void> {
+  if (driver !== "sqlite" || !foreignKeys) return;
+  try {
+    await sql`PRAGMA foreign_keys = ON`;
+  } catch {
+    // A driver that will not take the pragma is not a reason to refuse the
+    // connection; the doctor check reports the consequence.
+  }
+}

package/src/schema/Migration.ts

@@ -27,6 +27,36 @@
  * ```
  */
 export abstract class Migration {
+  /**
+   * The name this migration is recorded under, instead of its filename.
+   *
+   * **Identity is a filename by default, and a filename is a thing people rename.**
+   * The `migrations` table stores the name a migration ran as, and the next run
+   * compares files against it — so renaming a file makes an applied migration look
+   * pending, the runner tries it again, and it fails on `table already exists`. That
+   * is a failed boot rather than a graceful skip.
+   *
+   * It is not a hypothetical. An app renumbered `001_` to `0001_` to match this
+   * framework's own scaffold convention — exactly what a careful person does — and
+   * would have made all nine of its production migrations look unrun. They caught it
+   * before deploying and renamed the files back.
+   *
+   * Declaring `id` decouples the two. Set it to whatever the file is *already*
+   * recorded as, and the file is then free to be named anything:
+   *
+   * ```ts
+   * export default class AddTenantLimits extends Migration {
+   *   static override id = "010_add_tenant_limits"; // what the table already holds
+   *   async up() { … }
+   * }
+   * ```
+   *
+   * Deliberately not a content hash: a migration's content is edited far more often
+   * than its name, and a hash would make every edit look like a new migration — the
+   * same failure, more often.
+   */
+  static id?: string;
+
   /** Apply the migration's forward schema change. */
   abstract up(): Promise<void>;
   /** Reverse everything {@link Migration.up} did, for rollback. */

package/src/schema/MigrationRunner.ts

@@ -150,6 +150,8 @@ export class MigrationRunner {
     const batch = (await this._lastBatch()) + 1;
 
     const pendingEntries = entries.filter((e) => !ran.has(e.name));
+    _refuseLikelyRenames(pendingEntries, ran);
+
     const executed: string[] = [];
 
     for (const entry of pendingEntries) {
@@ -425,11 +427,75 @@ export class MigrationRunner {
       // Dynamic import — each migration file must have a default export
       const mod = (await import(fullPath)) as { default: new () => Migration };
       const Ctor = mod.default;
+      // A declared `static id` wins over the filename — see `Migration.id`. Without
+      // it, renaming a file makes an applied migration look pending.
+      const declared = (Ctor as { id?: string }).id;
       entries.push({
-        name: file.replace(/\.(ts|js)$/, ""),
+        name: declared ?? file.replace(/\.(ts|js)$/, ""),
         migration: new Ctor(),
       });
     }
     return entries;
   }
 }
+
+/**
+ * Refuse to run a "pending" migration that is almost certainly a renamed applied one.
+ *
+ * A migration is recorded under a name, and the next run compares files against those
+ * names — so renaming a file makes an applied migration look pending. The runner then
+ * tries it again and it fails on `table already exists`, which is a failed boot rather
+ * than a graceful skip, and the error names a table rather than the rename that caused
+ * it.
+ *
+ * An app renumbered `001_` to `0001_` to match this framework's own scaffold
+ * convention and would have made all nine of its production migrations look unrun.
+ * They caught it by reading, not by being told.
+ *
+ * The signal is precise enough to act on: a pending migration whose name matches a
+ * recorded one once the leading digits are stripped is a renumbering, not a new
+ * migration. Nobody writes `0001_create_users` alongside an applied
+ * `001_create_users` and means two different things.
+ *
+ * This refuses rather than warns because the alternative is running it — and running
+ * it is the outage. {@link Migration.id} is the way to make the rename permanent.
+ *
+ * @param pending - Migrations about to run.
+ * @param ran - Names already recorded.
+ * @throws {@link MigrationError} naming both spellings and the fix.
+ * @internal
+ */
+export function _refuseLikelyRenames(pending: MigrationEntry[], ran: Set<string>): void {
+  /** The name with any leading ordinal removed: `0001_create_users` → `create_users`. */
+  const withoutOrdinal = (name: string): string => name.replace(/^[0-9]+[_-]?/, "");
+
+  const appliedBySuffix = new Map<string, string>();
+  for (const name of ran) appliedBySuffix.set(withoutOrdinal(name), name);
+
+  for (const entry of pending) {
+    const suffix = withoutOrdinal(entry.name);
+    // A bare ordinal strips to nothing; two of those are not evidence of anything.
+    if (suffix === "") continue;
+    const applied = appliedBySuffix.get(suffix);
+    if (applied === undefined || applied === entry.name) continue;
+
+    throw new MigrationError(
+      entry.name,
+      new Error(
+        `"${entry.name}" looks like "${applied}", which has already run — the same ` +
+          `migration renumbered rather than a new one. Running it would apply a schema ` +
+          `change that is already applied, and fail on the first table it creates.
+
+` +
+          `  If it IS the same migration: rename the file back to "${applied}", or keep ` +
+          `the new filename and pin the identity to what the database already holds:
+` +
+          `    static override id = "${applied}";
+
+` +
+          `  If it is genuinely a new migration, give it a name that does not collide ` +
+          `once the leading digits are removed.`,
+      ),
+    );
+  }
+}