@c9up/atlas 0.2.0 → 0.2.1

package/src/schema/MigrationRunner.ts

@@ -4,6 +4,7 @@
  * @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";
@@ -14,11 +15,33 @@ import {
 	assertSafeName,
 	pathExists,
 } from "../utils/safePath.js";
-import { listUserTables, withoutForeignKeys } from "./catalog.js";
+import {
+	type CatalogConnection,
+	columnExists,
+	listUserTables,
+	runWithoutForeignKeys,
+	tableExists,
+} from "./catalog.js";
 import type { DeferredMigrationCallback, Migration } from "./Migration.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: string): string[] {
+	return sql
+		.split(";")
+		.map((s) => s.trim())
+		.filter((s) => s.replace(/^\s*--.*$/gm, "").trim().length > 0);
+}
 
 function validateTrackingTableName(name: string): string {
 	if (!TABLE_NAME_PATTERN.test(name)) {
@@ -68,6 +91,17 @@ export interface DatabaseAdapter {
 	 * "Migrations non transactionnelles" in the remediation audit).
 	 */
 	runInTransaction?(batch: readonly BatchStmt[]): Promise<number>;
+	/**
+	 * Optional MANAGED interactive transaction pinned to one connection (Lucid
+	 * `db.transaction(cb)`): commit on success, rollback on throw. Real
+	 * connections (`createNapiConnection`), the provider and the CLI all supply
+	 * it. It is REQUIRED for the two operations whose strong guarantee cannot be
+	 * faked without it: `this.defer()` (its callbacks must share the migration's
+	 * transaction) and MySQL FK suspension (a session-level `SET` needs a real
+	 * `finally` to restore). Both REJECT rather than silently degrade when it is
+	 * absent — plain migrations without either feature don't need it.
+	 */
+	transaction?<T>(callback: (trx: CatalogConnection) => Promise<T>): Promise<T>;
 	/** Close the connection. */
 	close(): Promise<void>;
 }
@@ -124,7 +158,11 @@ export class MigrationRunner {
 	 */
 	#disableRollbacksInProduction: boolean;
 	#disableLocks: boolean;
+	#disableTransactions: boolean;
+	#naturalSort: boolean;
 	#lockTableName: string;
+	/** Token identifying the lock WE hold, so release only clears our own lock. */
+	#lockToken: string | undefined;
 
 	constructor(
 		db: DatabaseAdapter,
@@ -133,9 +171,11 @@ export class MigrationRunner {
 			dialect?: AtlasDialect;
 			tableName?: string;
 			/**
-			 * Refuse `rollback`/`reset` when `NODE_ENV === 'production'` (Adonis
-			 * Lucid `disableRollbacksInProduction`) — a guard against dropping
-			 * production data by accident. Override per call with `{ force: true }`.
+			 * Refuse destructive ops (rollback/reset/refresh/fresh/wipe) when
+			 * `NODE_ENV === 'production'` (Adonis Lucid `disableRollbacksInProduction`)
+			 * — a guard against dropping production data by accident. **Defaults to
+			 * ON**, matching Lucid: a destructive migration command in production
+			 * throws unless `{ force: true }` (CLI `--force`). Pass `false` to opt out.
 			 */
 			disableRollbacksInProduction?: boolean;
 			/**
@@ -144,6 +184,21 @@ export class MigrationRunner {
 			 * so it prevents concurrent migrations on every dialect, SQLite too.
 			 */
 			disableLocks?: boolean;
+			/**
+			 * Run EVERY migration outside a transaction (Adonis Lucid global
+			 * `migrations.disableTransactions`). A single migration can also opt out
+			 * on its own with `static disableTransactions = true`; the effective value
+			 * is the OR of the two. Defaults to `false` — migrations are wrapped in a
+			 * transaction for clean, all-or-nothing rollbacks.
+			 */
+			disableTransactions?: boolean;
+			/**
+			 * Sort migration files with a numeric-aware comparator (Adonis Lucid
+			 * `migrations.naturalSort`), so `2_x` orders before `10_x`. Defaults to
+			 * `false` — plain lexicographic order, which is already correct for the
+			 * fixed-width `Date.now()` prefixes `make:migration` generates.
+			 */
+			naturalSort?: boolean;
 		},
 	) {
 		this.#db = db;
@@ -153,9 +208,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`;
 	}
 
@@ -171,10 +230,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,
@@ -196,34 +259,92 @@ 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<{ c: number }>(
-			`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(): string {
+		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(): string {
+		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(): Promise<void> {
 		if (this.#disableLocks) return;
 		await this.#ensureLockTable();
-		const rows = await this.#db.query<{ is_locked: unknown }>(
-			`SELECT is_locked FROM ${this.#lockTableName}`,
+		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 locked = rows[0]?.is_locked;
-		if (locked === 1 || locked === true || locked === "1") {
+		const rows = await this.#db.query<{ locked_by: unknown }>(
+			`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.",
@@ -232,18 +353,62 @@ export class MigrationRunner {
 				},
 			);
 		}
-		await this.#db.execute(`UPDATE ${this.#lockTableName} SET is_locked = 1`);
+		this.#lockToken = token;
+	}
+
+	/** Run `fn` while holding the migration lock; always release, even on throw. */
+	async #withLock<T>(fn: () => Promise<T>): Promise<T> {
+		await this.#acquireLock();
+		try {
+			return await fn();
+		} finally {
+			await this.#releaseLock();
+		}
 	}
 
-	/** Release the migration lock (clears the `is_locked` flag). */
+	/** Release the migration lock — only OUR token, so we never clear someone else's. */
 	async #releaseLock(): Promise<void> {
-		if (this.#disableLocks) return;
-		await this.#db.execute(`UPDATE ${this.#lockTableName} SET is_locked = 0`);
+		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],
+		);
 	}
 
 	/**
-	 * 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(): Promise<boolean> {
+		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<{ is_locked: unknown }>(
+			`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: boolean): void {
 		if (
@@ -253,7 +418,7 @@ export class MigrationRunner {
 		) {
 			throw new AtlasError(
 				"E_ROLLBACK_DISABLED_IN_PRODUCTION",
-				"Rollbacks are disabled in production. Pass { force: true } to override.",
+				"Destructive migration operations are disabled in production. Pass { force: true } to override.",
 				{
 					hint: "This guard exists to prevent dropping production data by accident.",
 				},
@@ -327,24 +492,30 @@ export class MigrationRunner {
 
 	/** Get the status of all migrations. */
 	async status(): Promise<MigrationStatus[]> {
-		// 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<MigrationRecord>(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: MigrationRecord[] = (await tableExists(
+			this.#db,
+			this.#dialect,
+			this.#tableName,
+		))
+			? await queryStmt<MigrationRecord>(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();
@@ -356,16 +527,15 @@ export class MigrationRunner {
 	}
 
 	/** Run all pending migrations. */
-	async migrate(): Promise<string[]> {
-		await this.#acquireLock();
-		try {
-			return await this.#migrateLocked();
-		} finally {
-			await this.#releaseLock();
-		}
+	async migrate(options: { schemaPath?: string } = {}): Promise<string[]> {
+		return this.#withLock(() => this.#migrateLocked(options.schemaPath));
 	}
 
-	async #migrateLocked(): Promise<string[]> {
+	async #migrateLocked(schemaPath?: string): Promise<string[]> {
+		// 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<MigrationRecord>(this.#db, this.#dialect, {
@@ -398,6 +568,10 @@ 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
@@ -426,6 +600,7 @@ export class MigrationRunner {
 				deferred,
 				{ sql: insertSql, params: insertCompiled.params },
 				name,
+				disableTx,
 			);
 			executed.push(name);
 		}
@@ -438,12 +613,7 @@ export class MigrationRunner {
 		options: { batch?: number; force?: boolean } = {},
 	): Promise<string[]> {
 		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: {
@@ -496,6 +666,9 @@ 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(
 				{
@@ -520,6 +693,7 @@ export class MigrationRunner {
 				deferred,
 				{ sql: deleteSql, params: deleteCompiled.params },
 				record.name,
+				disableTx,
 			);
 			rolled.push(record.name);
 		}
@@ -527,40 +701,101 @@ export class MigrationRunner {
 		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: string[],
 		deferred: DeferredMigrationCallback[],
 		recordStmt: BatchStmt,
 		migrationName: string,
+		disableTransactions: boolean,
 	): Promise<void> {
 		const schemaBatch: BatchStmt[] = statements.map((sql) => ({
 			sql,
 			params: [] as unknown[],
 		}));
+		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(
@@ -590,9 +825,14 @@ export class MigrationRunner {
 	async refresh(
 		options: { force?: boolean } = {},
 	): Promise<{ rolled: string[]; executed: string[] }> {
-		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 };
+		});
 	}
 
 	/**
@@ -608,10 +848,76 @@ export class MigrationRunner {
 	 *
 	 * `rolled` is always empty — fresh drops rather than rolls back.
 	 */
-	async fresh(): Promise<{ rolled: string[]; executed: string[] }> {
-		await this.#dropAllTables();
-		const executed = await this.migrate();
-		return { rolled: [], executed };
+	async fresh(
+		options: { force?: boolean; schemaPath?: string } = {},
+	): Promise<{ rolled: string[]; executed: string[] }> {
+		// `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: string): Promise<void> {
+		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?: string): Promise<void> {
+		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(): Promise<boolean> {
+		if (!(await tableExists(this.#db, this.#dialect, this.#tableName))) {
+			return false;
+		}
+		const rows = await this.#db.query<{ n: number }>(
+			`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: string): string {
+		return this.#dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
 	}
 
 	/**
@@ -624,30 +930,60 @@ export class MigrationRunner {
 	 * duration (they don't accept/respect CASCADE on `DROP TABLE`), restored
 	 * even if a drop throws.
 	 */
-	async wipe(): Promise<void> {
-		return this.#dropAllTables();
+	async wipe(options: { force?: boolean } = {}): Promise<void> {
+		// `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(): Promise<void> {
 		// 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, {
-			includeFrameworkTables: true,
-		});
+		// 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: Array<{ sql: string; params?: unknown[] }> = [];
+		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);
 	}
 
 	/**
@@ -656,11 +992,16 @@ export class MigrationRunner {
 	 */
 	async reset(options: { force?: boolean } = {}): Promise<string[]> {
 		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(): Promise<string[]> {
 		await this.init();
 		const all: string[] = [];
-		// 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);
 		}
@@ -673,22 +1014,31 @@ export class MigrationRunner {
 	 * migration file. Useful for CI pre-flight checks.
 	 */
 	async dryRun(): Promise<Array<{ name: string; sql: string[] }>> {
-		await this.init();
-		const applied = await queryStmt<MigrationRecord>(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<string>();
+		if (await tableExists(this.#db, this.#dialect, this.#tableName)) {
+			const applied = await queryStmt<MigrationRecord>(
+				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),
 		);
@@ -697,6 +1047,9 @@ export class MigrationRunner {
 		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 });
 		}
@@ -726,10 +1079,21 @@ export class MigrationRunner {
 	async #discoverFiles(): Promise<string[]> {
 		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.
 			if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];