@c9up/atlas 0.1.19 → 0.2.1

package/dist/schema/MigrationRunner.js

@@ -3,14 +3,31 @@
  *
  * @implements FR34
  */
+import { randomUUID } from "node:crypto";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import { AtlasError } from "../errors.js";
 import { compileStatementNative } from "../query/native.js";
 import { assertPathInsideBase, assertSafeName, pathExists, } from "../utils/safePath.js";
+import { columnExists, listUserTables, runWithoutForeignKeys, tableExists, } from "./catalog.js";
+import { readSchemaDumpManifest } from "./SchemaDumper.js";
 const DEFAULT_TABLE = "ream_migrations";
 const TABLE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The single lock row's fixed primary key — the lock is always this one row. */
+const LOCK_ROW_ID = 1;
+/**
+ * Split a schema-dump `.sql` file into executable statements. Statements are
+ * `;`-terminated (the dump format atlas writes); chunks that are empty or only
+ * SQL comments once trimmed are dropped. Leading `--` comment lines on a real
+ * statement are kept (every dialect parses a comment before a statement).
+ */
+function splitSqlStatements(sql) {
+    return sql
+        .split(";")
+        .map((s) => s.trim())
+        .filter((s) => s.replace(/^\s*--.*$/gm, "").trim().length > 0);
+}
 function validateTrackingTableName(name) {
     if (!TABLE_NAME_PATTERN.test(name)) {
         throw new AtlasError("MIGRATION_INVALID_TABLE_NAME", `Invalid tracking-table name: ${JSON.stringify(name)}. ` +
@@ -46,7 +63,8 @@ export class MigrationRunner {
      *   throws `AtlasError("MIGRATION_INVALID_TABLE_NAME")` synchronously otherwise.
      *
      *   Cleanup coupling: `DatabaseCleanup.truncateAll` (`src/testing/DatabaseCleanup.ts`)
-     *   skips tables whose name starts with `ream_` (via `LIKE 'ream\_%' ESCAPE '\'`).
+     *   skips tables whose name starts with `ream_` (filtered in JS by the shared
+     *   catalog helper, `src/schema/catalog.ts`).
      *   The default `"ream_migrations"` is therefore auto-protected. Choosing a name
      *   without the `ream_` prefix (e.g. `"schema_versions"`) opts the tracking table
      *   out of that protection — `truncateAll` will wipe it alongside user tables,
@@ -63,6 +81,13 @@ export class MigrationRunner {
      *     INSERT INTO schema_versions SELECT * FROM ream_migrations;
      *     -- (then DROP TABLE ream_migrations once verified)
      */
+    #disableRollbacksInProduction;
+    #disableLocks;
+    #disableTransactions;
+    #naturalSort;
+    #lockTableName;
+    /** Token identifying the lock WE hold, so release only clears our own lock. */
+    #lockToken;
     constructor(db, options) {
         this.#db = db;
         this.#migrationsDir = options?.migrationsDir ?? "database/migrations";
@@ -71,6 +96,186 @@ export class MigrationRunner {
             options?.tableName === undefined
                 ? DEFAULT_TABLE
                 : validateTrackingTableName(options.tableName);
+        // Defaults ON (Lucid parity): destructive ops are guarded in production
+        // unless the caller explicitly opts out or forces per call.
+        this.#disableRollbacksInProduction =
+            options?.disableRollbacksInProduction ?? true;
+        this.#disableLocks = options?.disableLocks ?? false;
+        this.#disableTransactions = options?.disableTransactions ?? false;
+        this.#naturalSort = options?.naturalSort ?? false;
+        this.#lockTableName = `${this.#tableName}_lock`;
+    }
+    /**
+     * Ensure the lock table exists and holds exactly one row. Mirrors the Knex /
+     * AdonisJS Lucid migration-lock mechanism: a `<tableName>_lock` table with an
+     * `is_locked` flag (NOT a Postgres advisory lock), so it works identically on
+     * every dialect, SQLite included.
+     */
+    async #ensureLockTable() {
+        await runStmt(this.#db, this.#dialect, {
+            kind: "createTable",
+            table: this.#lockTableName,
+            ifNotExists: true,
+            columns: [
+                // A FIXED single-row identity (id = LOCK_ROW_ID, PK). Not
+                // auto-increment: every acquire/release/seed targets `WHERE id = 1`,
+                // so a duplicate row is impossible (the PK rejects it). That removes
+                // any need for a "recover from multi-row" DELETE that could wipe an
+                // active lock held by another process.
+                {
+                    name: "id",
+                    kind: "integer",
+                    nullable: false,
+                    primary: true,
+                    unique: false,
+                    default: null,
+                    references: null,
+                    length: null,
+                    precision: null,
+                    scale: null,
+                },
+                {
+                    name: "is_locked",
+                    kind: "integer",
+                    nullable: false,
+                    primary: false,
+                    unique: false,
+                    default: null,
+                    references: null,
+                    length: null,
+                    precision: null,
+                    scale: null,
+                },
+                {
+                    name: "locked_by",
+                    kind: "string",
+                    nullable: true,
+                    primary: false,
+                    unique: false,
+                    default: null,
+                    references: null,
+                    length: null,
+                    precision: null,
+                    scale: null,
+                },
+            ],
+            indexes: [],
+        });
+        // Upgrade path: a lock table created by an earlier atlas (id + is_locked,
+        // no `locked_by`) is left untouched by CREATE TABLE IF NOT EXISTS, so the
+        // token UPDATE/SELECT below would hit a missing column. Add it if absent.
+        if (!(await columnExists(this.#db, this.#dialect, this.#lockTableName, "locked_by"))) {
+            try {
+                await this.#db.execute(`ALTER TABLE ${this.#lockTableName} ADD COLUMN locked_by TEXT`);
+            }
+            catch {
+                // TOCTOU: two concurrent first-boots on a legacy lock table can both
+                // see the column absent and both ALTER; the loser hits a
+                // duplicate-column error (no dialect has ADD COLUMN IF NOT EXISTS on
+                // all three). Swallow it — the column now exists either way; a real
+                // failure surfaces on the very next statement (seed/UPDATE).
+            }
+        }
+        // Seed the single lock row idempotently. INSERT-or-ignore on the PK means
+        // concurrent seeders and re-runs never create a second row and never touch
+        // an existing (possibly held) lock. The lock-table name derives from the
+        // validated tracking-table name — a safe identifier, no injection surface.
+        await this.#db.execute(this.#seedLockRowSql());
+    }
+    /** Dialect-specific idempotent seed of the single `id = 1` lock row. */
+    #seedLockRowSql() {
+        const t = this.#lockTableName;
+        const values = `(${LOCK_ROW_ID}, 0)`;
+        switch (this.#dialect) {
+            case "sqlite":
+                return `INSERT OR IGNORE INTO ${t} (id, is_locked) VALUES ${values}`;
+            case "mysql":
+                return `INSERT IGNORE INTO ${t} (id, is_locked) VALUES ${values}`;
+            case "postgres":
+                return `INSERT INTO ${t} (id, is_locked) VALUES ${values} ON CONFLICT (id) DO NOTHING`;
+        }
+    }
+    /** Dialect placeholder for a single bound parameter. */
+    get #ph() {
+        return this.#dialect === "postgres" ? "$1" : "?";
+    }
+    /**
+     * Acquire the migration lock so two processes cannot migrate concurrently
+     * (Adonis Lucid / Knex parity — a lock TABLE, not an advisory lock).
+     *
+     * ATOMIC: a single conditional `UPDATE … WHERE is_locked = 0` stamps our
+     * token — the database serialises concurrent updates on that row, so only ONE
+     * writer flips 0→1; every other writer's `WHERE` no longer matches. The
+     * token read-back tells us whether WE won. This avoids the check-then-set
+     * race of a separate SELECT + UPDATE. Throws `E_MIGRATION_LOCKED` otherwise.
+     */
+    async #acquireLock() {
+        if (this.#disableLocks)
+            return;
+        await this.#ensureLockTable();
+        const token = randomUUID();
+        await this.#db.execute(`UPDATE ${this.#lockTableName} SET is_locked = 1, locked_by = ${this.#ph} WHERE id = ${LOCK_ROW_ID} AND is_locked = 0`, [token]);
+        const rows = await this.#db.query(`SELECT locked_by FROM ${this.#lockTableName} WHERE id = ${LOCK_ROW_ID}`);
+        if (rows[0]?.locked_by !== token) {
+            throw new AtlasError("E_MIGRATION_LOCKED", "Could not acquire the migration lock — another migration is already running.", {
+                hint: `Wait for it to finish, clear the ${this.#lockTableName} table if it is stuck, or pass disableLocks.`,
+            });
+        }
+        this.#lockToken = token;
+    }
+    /** Run `fn` while holding the migration lock; always release, even on throw. */
+    async #withLock(fn) {
+        await this.#acquireLock();
+        try {
+            return await fn();
+        }
+        finally {
+            await this.#releaseLock();
+        }
+    }
+    /** Release the migration lock — only OUR token, so we never clear someone else's. */
+    async #releaseLock() {
+        if (this.#disableLocks || this.#lockToken === undefined)
+            return;
+        const token = this.#lockToken;
+        this.#lockToken = undefined;
+        await this.#db.execute(`UPDATE ${this.#lockTableName} SET is_locked = 0, locked_by = NULL WHERE id = ${LOCK_ROW_ID} AND locked_by = ${this.#ph}`, [token]);
+    }
+    /**
+     * Force-clear a stuck migration lock (Adonis Lucid `migration:unlock`). A
+     * process killed mid-migrate leaves `is_locked = 1` with a stale token and
+     * NO way for a later run to acquire — this unconditionally clears the row so
+     * migrations can proceed. Returns `true` if a held lock was cleared.
+     */
+    async forceUnlock() {
+        if (!(await tableExists(this.#db, this.#dialect, this.#lockTableName))) {
+            return false;
+        }
+        // Upgrade a legacy lock table (id + is_locked, no `locked_by`) BEFORE the
+        // `locked_by = NULL` UPDATE below — otherwise it hits a missing column and
+        // throws instead of clearing the stuck lock. `#ensureLockTable` is
+        // idempotent (CREATE IF NOT EXISTS + ALTER-add + idempotent seed).
+        await this.#ensureLockTable();
+        const rows = await this.#db.query(`SELECT is_locked FROM ${this.#lockTableName} WHERE id = ${LOCK_ROW_ID}`);
+        const wasLocked = rows[0]?.is_locked === 1 ||
+            rows[0]?.is_locked === true ||
+            rows[0]?.is_locked === "1";
+        await this.#db.execute(`UPDATE ${this.#lockTableName} SET is_locked = 0, locked_by = NULL WHERE id = ${LOCK_ROW_ID}`);
+        return wasLocked;
+    }
+    /**
+     * Throw when destructive migration operations (rollback / reset / refresh /
+     * fresh / wipe) are disabled in production and this is a production run,
+     * unless the caller explicitly forces it.
+     */
+    #assertRollbackAllowed(force) {
+        if (this.#disableRollbacksInProduction &&
+            !force &&
+            process.env.NODE_ENV === "production") {
+            throw new AtlasError("E_ROLLBACK_DISABLED_IN_PRODUCTION", "Destructive migration operations are disabled in production. Pass { force: true } to override.", {
+                hint: "This guard exists to prevent dropping production data by accident.",
+            });
+        }
     }
     /** Ensure the ream_migrations tracking table exists. */
     async init() {
@@ -137,20 +342,26 @@ export class MigrationRunner {
     }
     /** Get the status of all migrations. */
     async status() {
-        const applied = await queryStmt(this.#db, this.#dialect, {
-            kind: "select",
-            table: this.#tableName,
-            select: ["name", "batch"],
-            wheres: [],
-            orderBy: [{ column: "name", direction: "asc" }],
-            groupBy: [],
-            having: [],
-            limit: null,
-            offset: null,
-            distinct: false,
-            ctes: [],
-            unions: [],
-        });
+        // READ-ONLY: do NOT init() (which would CREATE the tracking table). On a
+        // never-migrated database the table is simply absent → everything pending,
+        // no side effect (AdonisJS/Lucid `migration:status` parity, same guarantee
+        // as dryRun).
+        const applied = (await tableExists(this.#db, this.#dialect, this.#tableName))
+            ? await queryStmt(this.#db, this.#dialect, {
+                kind: "select",
+                table: this.#tableName,
+                select: ["name", "batch"],
+                wheres: [],
+                orderBy: [{ column: "name", direction: "asc" }],
+                groupBy: [],
+                having: [],
+                limit: null,
+                offset: null,
+                distinct: false,
+                ctes: [],
+                unions: [],
+            })
+            : [];
         const appliedMap = new Map(applied.map((r) => [r.name, r.batch]));
         const files = await this.#discoverFiles();
         return files.map((f) => ({
@@ -160,7 +371,14 @@ export class MigrationRunner {
         }));
     }
     /** Run all pending migrations. */
-    async migrate() {
+    async migrate(options = {}) {
+        return this.#withLock(() => this.#migrateLocked(options.schemaPath));
+    }
+    async #migrateLocked(schemaPath) {
+        // Adonis Lucid `migration:run --schema-path`: when nothing is applied yet
+        // and a dump exists, load it in place of replaying history, then run only
+        // the migrations that postdate the dump (below, via the normal pending set).
+        await this.#maybeLoadDump(schemaPath);
         await this.init();
         const applied = await queryStmt(this.#db, this.#dialect, {
             kind: "select",
@@ -187,7 +405,11 @@ export class MigrationRunner {
         for (const name of pending) {
             this.#assertSafeName(name);
             const migration = await this.#loadMigration(name);
-            const statements = await migration.getUpSQL();
+            const statements = await migration.getUpSQL(this.#db);
+            const deferred = migration.consumeDeferred();
+            // Effective opt-out: the global config OR this migration's own
+            // `static disableTransactions = true`.
+            const disableTx = this.#disableTransactions || migration.transactionsDisabled;
             // Compile the ream_migrations INSERT so we can include it in the same
             // transaction as the migration's own DDL/DML — either everything
             // commits or nothing does.
@@ -203,27 +425,36 @@ export class MigrationRunner {
             if (insertSql === undefined) {
                 throw new AtlasError("MIGRATION_COMPILE_EMPTY", `compileStatementNative returned no statements for migration insert of '${name}'`);
             }
-            const batchStatements = [
-                ...statements.map((sql) => ({ sql, params: [] })),
-                { sql: insertSql, params: insertCompiled.params },
-            ];
-            await this.#runAtomic(batchStatements, name);
+            await this.#runStep(statements, deferred, { sql: insertSql, params: insertCompiled.params }, name, disableTx);
             executed.push(name);
         }
         return executed;
     }
     /** Rollback the last batch of migrations. */
-    async rollback() {
+    async rollback(options = {}) {
+        this.#assertRollbackAllowed(options.force ?? false);
+        return this.#withLock(() => this.#rollbackLocked(options));
+    }
+    async #rollbackLocked(options) {
         await this.init();
-        const batch = await this.#currentBatch();
-        if (batch === 0) {
+        const current = await this.#currentBatch();
+        if (current === 0) {
+            return [];
+        }
+        // Default: roll back only the latest batch. With `batch: N`, roll back
+        // every migration applied AFTER batch N (Lucid's `--batch` — a target to
+        // return to, not a count). `batch: 0` rolls the whole history back.
+        const target = options.batch ?? current - 1;
+        if (target >= current) {
             return [];
         }
         const toRollback = await queryStmt(this.#db, this.#dialect, {
             kind: "select",
             table: this.#tableName,
             select: ["name"],
-            wheres: [{ column: "batch", operator: "=", value: batch, type: "and" }],
+            wheres: [
+                { column: "batch", operator: ">", value: target, type: "and" },
+            ],
             // Reverse INSERTION order (auto-increment `id`), not name order — a
             // date- or hash-prefixed naming scheme would otherwise roll back in
             // the wrong sequence. `id DESC` is always the inverse of application.
@@ -240,7 +471,10 @@ export class MigrationRunner {
         for (const record of toRollback) {
             this.#assertSafeName(record.name);
             const migration = await this.#loadMigration(record.name);
-            const statements = await migration.getDownSQL();
+            const statements = await migration.getDownSQL(this.#db);
+            const deferred = migration.consumeDeferred();
+            // `static disableTransactions` applies to down() too (Adonis parity).
+            const disableTx = this.#disableTransactions || migration.transactionsDisabled;
             const deleteCompiled = compileStatementNative({
                 kind: "delete",
                 table: this.#tableName,
@@ -252,20 +486,95 @@ export class MigrationRunner {
             if (deleteSql === undefined) {
                 throw new AtlasError("MIGRATION_COMPILE_EMPTY", `compileStatementNative returned no statements for migration delete of '${record.name}'`);
             }
-            const batchStatements = [
-                ...statements.map((sql) => ({ sql, params: [] })),
-                { sql: deleteSql, params: deleteCompiled.params },
-            ];
-            await this.#runAtomic(batchStatements, record.name);
+            await this.#runStep(statements, deferred, { sql: deleteSql, params: deleteCompiled.params }, record.name, disableTx);
             rolled.push(record.name);
         }
         return rolled;
     }
     /**
-     * Run a batch of statements in a single transaction if the adapter supports
-     * it; otherwise fall back to sequential execute (best-effort). Adapters that
-     * lack transaction support get a warning so integrators notice the risk.
+     * Run one migration step: its schema statements plus the bookkeeping record
+     * write (INSERT for migrate, DELETE for rollback).
+     *
+     * With no deferred callbacks, schema + record commit together in one atomic
+     * batch. With `this.defer()` callbacks and an adapter that exposes an
+     * interactive `transaction()`, the schema, the deferred callbacks AND the
+     * record write all run in ONE transaction — a throwing callback rolls the
+     * schema back too (fully atomic on sqlite/postgres; MySQL auto-commits DDL, so
+     * only its tracking row is bound to the callbacks). An adapter with no
+     * `transaction()` cannot make defer atomic, so it is REJECTED with
+     * `E_DEFER_REQUIRES_TRANSACTION` rather than silently degrading to a
+     * schema-then-callbacks-then-record best effort.
+     *
+     * When `disableTransactions` is set (Adonis `static disableTransactions` / the
+     * global config — a DELIBERATE opt-out for txn-incompatible DDL), every
+     * statement runs OUTSIDE a transaction: schema, then deferred callbacks, then
+     * the record, each committed on its own. Non-atomic by design, so defer runs
+     * loose here and no `transaction()` is required.
      */
+    async #runStep(statements, deferred, recordStmt, migrationName, disableTransactions) {
+        const schemaBatch = statements.map((sql) => ({
+            sql,
+            params: [],
+        }));
+        if (disableTransactions) {
+            // Deliberate opt-out (Adonis): run everything unwrapped. No transaction()
+            // needed and no throw — the caller has accepted non-atomicity for DDL that
+            // cannot run in a transaction (e.g. Postgres CREATE INDEX CONCURRENTLY).
+            if (deferred.length > 0) {
+                // The sharp edge: with the transaction gone, the schema, the deferred
+                // callbacks and the tracking row commit SEPARATELY, so a failing
+                // callback leaves the schema applied but the migration unrecorded.
+                // Adonis doesn't warn here — a named safety nudge so the non-atomicity
+                // of this exact combo is never a surprise. Make both the DDL and the
+                // deferred work idempotent (guarded DDL + re-runnable seeds).
+                console.warn(`[atlas] Migration '${migrationName}' combines this.defer() with disableTransactions — the schema, the deferred callbacks and the tracking row commit separately (non-atomic). Make the DDL and the deferred work idempotent.`);
+            }
+            for (const { sql, params } of schemaBatch) {
+                await this.#db.execute(sql, params);
+            }
+            for (const callback of deferred) {
+                await callback(this.#db);
+            }
+            await this.#db.execute(recordStmt.sql, recordStmt.params);
+            return;
+        }
+        if (deferred.length === 0) {
+            await this.#runAtomic([...schemaBatch, recordStmt], migrationName);
+            return;
+        }
+        // With deferred callbacks: run the schema, the callbacks, AND the tracking
+        // row in ONE managed interactive transaction (Lucid runs defer inside the
+        // migration transaction). A throwing callback then rolls back the schema
+        // too, so the migration is genuinely all-or-nothing / re-runnable — not
+        // left applied-but-unrecorded. Fully atomic on sqlite/postgres; MySQL
+        // auto-commits DDL so its schema part can't roll back, but the tracking row
+        // is still bound to the callbacks. Requires `transaction()` on the adapter.
+        if (this.#db.transaction) {
+            await this.#db.transaction(async (trx) => {
+                for (const { sql, params } of schemaBatch) {
+                    await trx.execute(sql, params);
+                }
+                for (const callback of deferred) {
+                    await callback(trx);
+                }
+                await trx.execute(recordStmt.sql, recordStmt.params);
+            });
+            return;
+        }
+        // No interactive transaction() available: this.defer() CANNOT be atomic —
+        // its callbacks must share the migration's transaction (Adonis wraps every
+        // migration in a transaction by default, so defer runs inside it). Refuse
+        // loudly rather than commit the schema and leave the migration half-applied
+        // behind a warning: a strong guarantee must never silently degrade to a
+        // weak one. Reached ONLY by a capability gap — an adapter that cannot do
+        // transactions at all (real connections, the provider and the CLI always
+        // can). This is NOT Adonis's `disableTransactions` opt-out (a deliberate
+        // per-migration choice for txn-incompatible DDL); if that parity feature is
+        // added, it must route its own non-atomic path, not trip this guard.
+        throw new AtlasError("E_DEFER_REQUIRES_TRANSACTION", `Migration '${migrationName}' uses this.defer(), which needs an interactive transaction() on the adapter to run atomically — this adapter has none.`, {
+            hint: "Use a real connection (createNapiConnection) or an adapter that implements transaction(); otherwise remove this.defer().",
+        });
+    }
     async #runAtomic(batch, migrationName) {
         if (this.#db.runInTransaction) {
             await this.#db.runInTransaction(batch);
@@ -284,30 +593,161 @@ export class MigrationRunner {
      *
      * @implements Story 32.11
      */
-    async refresh() {
-        const rolled = await this.reset();
-        const executed = await this.migrate();
-        return { rolled, executed };
+    async refresh(options = {}) {
+        this.#assertRollbackAllowed(options.force ?? false);
+        // One lock held across the WHOLE rollback+re-migrate, so no other run can
+        // slip into the free window between reset and migrate.
+        return this.#withLock(async () => {
+            const rolled = await this.#resetLocked();
+            const executed = await this.#migrateLocked();
+            return { rolled, executed };
+        });
+    }
+    /**
+     * Drop EVERY user table directly (no `down()`), then run every migration from
+     * scratch. `migrate:fresh` in Lucid parlance.
+     *
+     * Unlike {@link refresh} (which rolls back by calling each migration's
+     * `down()`), `fresh` wipes the tables outright — so it succeeds even when a
+     * `down()` is broken or missing, and it also clears orphan tables no migration
+     * tracks. This matches Lucid's `migration:fresh`. Views, types and domains are
+     * left intact: Lucid gates those behind opt-in flags (`--drop-views` /
+     * `--drop-types` / `--drop-domains`), so tables-only is its default.
+     *
+     * `rolled` is always empty — fresh drops rather than rolls back.
+     */
+    async fresh(options = {}) {
+        // `fresh` DROPS every table — at least as destructive as rollback, so it
+        // must honour the same production guard (Lucid runs it behind `--force` in
+        // prod). Held under the migration lock for the whole drop+migrate.
+        this.#assertRollbackAllowed(options.force ?? false);
+        return this.#withLock(async () => {
+            await this.#dropAllTables();
+            // With `--schema-path`, rebuild from the dump instead of replaying every
+            // migration file (Adonis Lucid `migration:fresh --schema-path`).
+            const executed = await this.#migrateLocked(options.schemaPath);
+            return { rolled: [], executed };
+        });
+    }
+    /**
+     * Load a schema dump (Adonis Lucid `SchemaDumper` output) into the database —
+     * executes every statement in the `.sql` file in order, recreating the tables
+     * AND the migration bookkeeping rows. Used by `--schema-path`; also callable
+     * directly to seed a fresh database from a committed dump.
+     */
+    async loadDump(sqlPath) {
+        const sql = await fsp.readFile(sqlPath, "utf8");
+        for (const statement of splitSqlStatements(sql)) {
+            await this.#db.execute(statement, []);
+        }
+    }
+    /** Load the dump only when `--schema-path` is set, it exists, and nothing is applied. */
+    async #maybeLoadDump(schemaPath) {
+        if (!schemaPath)
+            return;
+        if (await this.#hasAppliedMigrations())
+            return;
+        if (!(await pathExists(schemaPath)))
+            return;
+        // Validate the sidecar manifest first (throws on a corrupt one), then check
+        // it matches THIS runner — a dump for another dialect can't be loaded, and a
+        // different bookkeeping table would leave the runner unable to see the
+        // embedded applied-migration rows.
+        const manifest = await readSchemaDumpManifest(schemaPath);
+        if (manifest) {
+            if (manifest.dialect !== this.#dialect) {
+                throw new AtlasError("E_SCHEMA_DUMP_DIALECT_MISMATCH", `Schema dump is for '${manifest.dialect}', but this connection is '${this.#dialect}'.`);
+            }
+            if (manifest.schemaTableName !== this.#tableName) {
+                throw new AtlasError("E_SCHEMA_DUMP_TABLE_MISMATCH", `Schema dump uses tracking table '${manifest.schemaTableName}', but this runner expects '${this.#tableName}'.`);
+            }
+        }
+        await this.loadDump(schemaPath);
+    }
+    /** True when the tracking table exists AND has at least one applied row. */
+    async #hasAppliedMigrations() {
+        if (!(await tableExists(this.#db, this.#dialect, this.#tableName))) {
+            return false;
+        }
+        const rows = await this.#db.query(`SELECT COUNT(*) AS n FROM ${this.#quoteTable(this.#tableName)}`);
+        return Number(rows[0]?.n ?? 0) > 0;
+    }
+    /** Quote the tracking-table name for the current dialect. */
+    #quoteTable(name) {
+        return this.#dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
     }
     /**
-     * Drop EVERY table the migrations created (via successive rollbacks) then
-     * run every migration from scratch. `migrate:fresh` in Lucid parlance.
+     * Drop every user table — INCLUDING the migrations tracking table (Lucid's
+     * `db:wipe`). `fresh()` calls this and then re-migrates; a caller can use it
+     * directly to reset a database to empty.
      *
-     * Distinct from `refresh()` only in intent — both end up with a fresh DB.
+     * Inter-table foreign keys are handled per dialect: Postgres emits
+     * `DROP TABLE … CASCADE`; MySQL and SQLite suspend FK checks for the
+     * duration (they don't accept/respect CASCADE on `DROP TABLE`), restored
+     * even if a drop throws.
      */
-    async fresh() {
-        return this.refresh();
+    async wipe(options = {}) {
+        // `db:wipe` drops every table — same production guard as rollback/fresh.
+        this.#assertRollbackAllowed(options.force ?? false);
+        // Drop everything WHILE STILL HOLDING the lock — including the lock table
+        // itself as the last step — then null our token so the release is a no-op
+        // (the table is gone). Doing it inside the critical section leaves NO window
+        // for another process to acquire/recreate the lock and get dropped from
+        // under it. Result: a truly empty database.
+        await this.#acquireLock();
+        try {
+            await this.#dropAllTables();
+            // Always drop the lock table (IF EXISTS) so wipe leaves a truly empty DB
+            // — including when disableLocks is set and a PRIOR locked run created it.
+            // Under a held lock this is the last step in the critical section; under
+            // disableLocks we hold nothing, so dropping it is safe either way.
+            const compiled = compileStatementNative({ kind: "dropTable", table: this.#lockTableName, ifExists: true }, this.#dialect);
+            for (const sql of compiled.statements) {
+                await this.#db.execute(sql, compiled.params);
+            }
+            this.#lockToken = undefined;
+        }
+        finally {
+            await this.#releaseLock();
+        }
+    }
+    async #dropAllTables() {
+        // Include the tracking table: wipe/fresh reset to fully empty, and
+        // fresh() re-creates it via init() on the next migrate(). The lock table
+        // is deliberately KEPT — we're holding the lock through it, and dropping it
+        // mid-operation would break the release. It is infrastructure, not data.
+        const tables = (await listUserTables(this.#db, this.#dialect, {
+            includeFrameworkTables: true,
+        })).filter((t) => t !== this.#lockTableName);
+        if (tables.length === 0)
+            return;
+        const isPg = this.#dialect === "postgres";
+        const statements = [];
+        for (const table of tables) {
+            const compiled = compileStatementNative({ kind: "dropTable", table, ifExists: true, cascade: isPg }, this.#dialect);
+            for (const sql of compiled.statements) {
+                statements.push({ sql, params: compiled.params });
+            }
+        }
+        // FK toggle + every DROP run on ONE pinned connection (not scattered
+        // across the pool) — see `runWithoutForeignKeys`.
+        await runWithoutForeignKeys(this.#db, this.#dialect, statements);
     }
     /**
      * Rollback every applied batch (alias for `migrate:reset`).
      * Returns the list of rolled-back migration names (in rollback order).
      */
-    async reset() {
+    async reset(options = {}) {
+        this.#assertRollbackAllowed(options.force ?? false);
+        return this.#withLock(() => this.#resetLocked());
+    }
+    /** The reset loop, WITHOUT re-acquiring the lock — the caller holds it, so
+     * the whole reset is one atomic critical section (not lock-per-batch). */
+    async #resetLocked() {
         await this.init();
         const all = [];
-        // Roll back batches one by one until nothing remains.
         while ((await this.#currentBatch()) > 0) {
-            const rolled = await this.rollback();
+            const rolled = await this.#rollbackLocked({ batch: undefined });
             if (rolled.length === 0)
                 break;
             all.push(...rolled);
@@ -320,28 +760,37 @@ export class MigrationRunner {
      * migration file. Useful for CI pre-flight checks.
      */
     async dryRun() {
-        await this.init();
-        const applied = await queryStmt(this.#db, this.#dialect, {
-            kind: "select",
-            table: this.#tableName,
-            select: ["name"],
-            wheres: [],
-            orderBy: [],
-            groupBy: [],
-            having: [],
-            limit: null,
-            offset: null,
-            distinct: false,
-            ctes: [],
-            unions: [],
-        });
-        const appliedNames = new Set(applied.map((r) => r.name));
+        // A dry-run must be side-effect-free: do NOT call init() (it would CREATE
+        // the tracking table on an empty database). If the table doesn't exist
+        // yet, nothing has been applied.
+        const appliedNames = new Set();
+        if (await tableExists(this.#db, this.#dialect, this.#tableName)) {
+            const applied = await queryStmt(this.#db, this.#dialect, {
+                kind: "select",
+                table: this.#tableName,
+                select: ["name"],
+                wheres: [],
+                orderBy: [],
+                groupBy: [],
+                having: [],
+                limit: null,
+                offset: null,
+                distinct: false,
+                ctes: [],
+                unions: [],
+            });
+            for (const r of applied)
+                appliedNames.add(r.name);
+        }
         const files = (await this.#discoverFiles()).filter((f) => !appliedNames.has(f));
         const result = [];
         for (const name of files) {
             this.#assertSafeName(name);
             const migration = await this.#loadMigration(name);
-            const statements = await migration.getUpSQL();
+            // Adonis `this.dryRun`: let up()/down() branch on it while we only
+            // collect SQL and never execute or run deferred callbacks.
+            migration.dryRun = true;
+            const statements = await migration.getUpSQL(this.#db);
             result.push({ name, sql: statements });
         }
         return result;
@@ -368,10 +817,16 @@ export class MigrationRunner {
     async #discoverFiles() {
         try {
             const entries = await fsp.readdir(this.#migrationsDir);
-            return entries
-                .filter((f) => f.endsWith(".ts") || f.endsWith(".js"))
-                .sort()
-                .map((f) => f.replace(/\.(ts|js)$/, ""));
+            const files = entries.filter((f) => f.endsWith(".ts") || f.endsWith(".js"));
+            // naturalSort (Lucid): numeric-aware so `2_x` < `10_x`. Default: plain
+            // lexicographic (UTF-16), correct for fixed-width Date.now() prefixes.
+            files.sort(this.#naturalSort
+                ? (a, b) => a.localeCompare(b, undefined, {
+                    numeric: true,
+                    sensitivity: "base",
+                })
+                : undefined);
+            return files.map((f) => f.replace(/\.(ts|js)$/, ""));
         }
         catch (err) {
             // Missing directory → no migrations. Any other error propagates.