@c9up/atlas 0.2.0 → 0.2.1

package/dist/schema/MigrationRunner.js

@@ -3,15 +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 { listUserTables, withoutForeignKeys } from "./catalog.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)}. ` +
@@ -67,7 +83,11 @@ export class MigrationRunner {
      */
     #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";
@@ -76,9 +96,13 @@ 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 ?? false;
+            options?.disableRollbacksInProduction ?? true;
         this.#disableLocks = options?.disableLocks ?? false;
+        this.#disableTransactions = options?.disableTransactions ?? false;
+        this.#naturalSort = options?.naturalSort ?? false;
         this.#lockTableName = `${this.#tableName}_lock`;
     }
     /**
@@ -93,10 +117,14 @@ export class MigrationRunner {
             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",
-                    autoIncrement: true,
                     nullable: false,
                     primary: true,
                     unique: false,
@@ -118,49 +146,133 @@ export class MigrationRunner {
                     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: [],
         });
-        // The lock-table name derives from the validated tracking-table name, so
-        // it is a safe identifier — no injection surface in these raw statements.
-        const rows = await this.#db.query(`SELECT COUNT(*) AS c FROM ${this.#lockTableName}`);
-        if (Number(rows[0]?.c ?? 0) === 0) {
-            await this.#db.execute(`INSERT INTO ${this.#lockTableName} (is_locked) VALUES (0)`);
+        // 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). Throws
-     * `E_MIGRATION_LOCKED` when the lock is already held.
+     * (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 rows = await this.#db.query(`SELECT is_locked FROM ${this.#lockTableName}`);
-        const locked = rows[0]?.is_locked;
-        if (locked === 1 || locked === true || locked === "1") {
+        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.`,
             });
         }
-        await this.#db.execute(`UPDATE ${this.#lockTableName} SET is_locked = 1`);
+        this.#lockToken = token;
     }
-    /** Release the migration lock (clears the `is_locked` flag). */
+    /** 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)
+        if (this.#disableLocks || this.#lockToken === undefined)
             return;
-        await this.#db.execute(`UPDATE ${this.#lockTableName} SET is_locked = 0`);
+        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]);
     }
     /**
-     * Throw when rollbacks are disabled in production and this is a production
-     * run, unless the caller explicitly forces it.
+     * 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", "Rollbacks are disabled in production. Pass { force: true } to override.", {
+            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.",
             });
         }
@@ -230,24 +342,26 @@ export class MigrationRunner {
     }
     /** Get the status of all migrations. */
     async status() {
-        // Ensure the tracking table exists first — on a never-migrated database
-        // status must report every migration as pending, not throw on a missing
-        // `ream_migrations` table (AdonisJS/Lucid `migration:status` parity).
-        await this.init();
-        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) => ({
@@ -257,16 +371,14 @@ export class MigrationRunner {
         }));
     }
     /** Run all pending migrations. */
-    async migrate() {
-        await this.#acquireLock();
-        try {
-            return await this.#migrateLocked();
-        }
-        finally {
-            await this.#releaseLock();
-        }
+    async migrate(options = {}) {
+        return this.#withLock(() => this.#migrateLocked(options.schemaPath));
     }
-    async #migrateLocked() {
+    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",
@@ -295,6 +407,9 @@ export class MigrationRunner {
             const migration = await this.#loadMigration(name);
             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.
@@ -310,7 +425,7 @@ export class MigrationRunner {
             if (insertSql === undefined) {
                 throw new AtlasError("MIGRATION_COMPILE_EMPTY", `compileStatementNative returned no statements for migration insert of '${name}'`);
             }
-            await this.#runStep(statements, deferred, { sql: insertSql, params: insertCompiled.params }, name);
+            await this.#runStep(statements, deferred, { sql: insertSql, params: insertCompiled.params }, name, disableTx);
             executed.push(name);
         }
         return executed;
@@ -318,13 +433,7 @@ export class MigrationRunner {
     /** Rollback the last batch of migrations. */
     async rollback(options = {}) {
         this.#assertRollbackAllowed(options.force ?? false);
-        await this.#acquireLock();
-        try {
-            return await this.#rollbackLocked(options);
-        }
-        finally {
-            await this.#releaseLock();
-        }
+        return this.#withLock(() => this.#rollbackLocked(options));
     }
     async #rollbackLocked(options) {
         await this.init();
@@ -364,6 +473,8 @@ export class MigrationRunner {
             const migration = await this.#loadMigration(record.name);
             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,
@@ -375,40 +486,94 @@ export class MigrationRunner {
             if (deleteSql === undefined) {
                 throw new AtlasError("MIGRATION_COMPILE_EMPTY", `compileStatementNative returned no statements for migration delete of '${record.name}'`);
             }
-            await this.#runStep(statements, deferred, { sql: deleteSql, params: deleteCompiled.params }, 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 this is the strong atomic path — schema + record
-     * commit together. With `this.defer()` callbacks, the schema runs atomically
-     * first, then the deferred callbacks, then the record write — so a failing
-     * deferred callback leaves the migration UN-recorded (re-runnable), at the
-     * cost of the schema no longer sharing a transaction with the record.
+     * 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) {
+    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;
         }
-        await this.#runAtomic(schemaBatch, migrationName);
-        for (const callback of deferred) {
-            await callback(this.#db);
+        // 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;
         }
-        await this.#db.execute(recordStmt.sql, recordStmt.params);
+        // 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) {
@@ -429,9 +594,14 @@ export class MigrationRunner {
      * @implements Story 32.11
      */
     async refresh(options = {}) {
-        const rolled = await this.reset(options);
-        const executed = await this.migrate();
-        return { rolled, executed };
+        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
@@ -446,10 +616,65 @@ export class MigrationRunner {
      *
      * `rolled` is always empty — fresh drops rather than rolls back.
      */
-    async fresh() {
-        await this.#dropAllTables();
-        const executed = await this.migrate();
-        return { rolled: [], executed };
+    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 user table — INCLUDING the migrations tracking table (Lucid's
@@ -461,26 +686,52 @@ export class MigrationRunner {
      * duration (they don't accept/respect CASCADE on `DROP TABLE`), restored
      * even if a drop throws.
      */
-    async wipe() {
-        return this.#dropAllTables();
+    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().
-        const tables = await listUserTables(this.#db, this.#dialect, {
+        // 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";
-        await withoutForeignKeys(this.#db, this.#dialect, async () => {
-            for (const table of tables) {
-                const compiled = compileStatementNative({ kind: "dropTable", table, ifExists: true, cascade: isPg }, this.#dialect);
-                for (const sql of compiled.statements) {
-                    await this.#db.execute(sql, compiled.params);
-                }
+        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`).
@@ -488,11 +739,15 @@ export class MigrationRunner {
      */
     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({ force: true });
+            const rolled = await this.#rollbackLocked({ batch: undefined });
             if (rolled.length === 0)
                 break;
             all.push(...rolled);
@@ -505,27 +760,36 @@ 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);
+            // 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 });
         }
@@ -553,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.