@c9up/atlas 0.1.19 → 0.2.0

package/src/schema/MigrationRunner.ts

@@ -14,7 +14,8 @@ import {
 	assertSafeName,
 	pathExists,
 } from "../utils/safePath.js";
-import type { Migration } from "./Migration.js";
+import { listUserTables, withoutForeignKeys } from "./catalog.js";
+import type { DeferredMigrationCallback, Migration } from "./Migration.js";
 
 const DEFAULT_TABLE = "ream_migrations";
 const TABLE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -103,7 +104,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,
@@ -120,12 +122,28 @@ export class MigrationRunner {
 	 *     INSERT INTO schema_versions SELECT * FROM ream_migrations;
 	 *     -- (then DROP TABLE ream_migrations once verified)
 	 */
+	#disableRollbacksInProduction: boolean;
+	#disableLocks: boolean;
+	#lockTableName: string;
+
 	constructor(
 		db: DatabaseAdapter,
 		options?: {
 			migrationsDir?: string;
 			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 }`.
+			 */
+			disableRollbacksInProduction?: boolean;
+			/**
+			 * Skip the migration lock (Adonis Lucid `--disable-locks`). The lock is
+			 * a `<tableName>_lock` table with an `is_locked` flag (Knex mechanism),
+			 * so it prevents concurrent migrations on every dialect, SQLite too.
+			 */
+			disableLocks?: boolean;
 		},
 	) {
 		this.#db = db;
@@ -135,6 +153,112 @@ export class MigrationRunner {
 			options?.tableName === undefined
 				? DEFAULT_TABLE
 				: validateTrackingTableName(options.tableName);
+		this.#disableRollbacksInProduction =
+			options?.disableRollbacksInProduction ?? false;
+		this.#disableLocks = options?.disableLocks ?? 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(): Promise<void> {
+		await runStmt(this.#db, this.#dialect, {
+			kind: "createTable",
+			table: this.#lockTableName,
+			ifNotExists: true,
+			columns: [
+				{
+					name: "id",
+					kind: "integer",
+					autoIncrement: true,
+					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,
+				},
+			],
+			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)`,
+			);
+		}
+	}
+
+	/**
+	 * 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.
+	 */
+	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 locked = rows[0]?.is_locked;
+		if (locked === 1 || locked === true || locked === "1") {
+			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`);
+	}
+
+	/** Release the migration lock (clears the `is_locked` flag). */
+	async #releaseLock(): Promise<void> {
+		if (this.#disableLocks) return;
+		await this.#db.execute(`UPDATE ${this.#lockTableName} SET is_locked = 0`);
+	}
+
+	/**
+	 * Throw when rollbacks are disabled in production and this is a production
+	 * run, unless the caller explicitly forces it.
+	 */
+	#assertRollbackAllowed(force: boolean): void {
+		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.",
+				{
+					hint: "This guard exists to prevent dropping production data by accident.",
+				},
+			);
+		}
 	}
 
 	/** Ensure the ream_migrations tracking table exists. */
@@ -203,6 +327,10 @@ 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,
@@ -229,6 +357,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 #migrateLocked(): Promise<string[]> {
 		await this.init();
 
 		const applied = await queryStmt<MigrationRecord>(this.#db, this.#dialect, {
@@ -259,7 +396,8 @@ 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();
 
 			// Compile the ream_migrations INSERT so we can include it in the same
 			// transaction as the migration's own DDL/DML — either everything
@@ -283,12 +421,12 @@ export class MigrationRunner {
 					`compileStatementNative returned no statements for migration insert of '${name}'`,
 				);
 			}
-			const batchStatements: BatchStmt[] = [
-				...statements.map((sql) => ({ sql, params: [] as unknown[] })),
+			await this.#runStep(
+				statements,
+				deferred,
 				{ sql: insertSql, params: insertCompiled.params },
-			];
-
-			await this.#runAtomic(batchStatements, name);
+				name,
+			);
 			executed.push(name);
 		}
 
@@ -296,11 +434,34 @@ export class MigrationRunner {
 	}
 
 	/** Rollback the last batch of migrations. */
-	async rollback(): Promise<string[]> {
+	async rollback(
+		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();
+		}
+	}
+
+	async #rollbackLocked(options: {
+		batch?: number;
+		force?: boolean;
+	}): Promise<string[]> {
 		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 [];
 		}
 
@@ -311,7 +472,9 @@ export class MigrationRunner {
 				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.
@@ -331,7 +494,8 @@ 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();
 
 			const deleteCompiled = compileStatementNative(
 				{
@@ -351,12 +515,12 @@ export class MigrationRunner {
 					`compileStatementNative returned no statements for migration delete of '${record.name}'`,
 				);
 			}
-			const batchStatements: BatchStmt[] = [
-				...statements.map((sql) => ({ sql, params: [] as unknown[] })),
+			await this.#runStep(
+				statements,
+				deferred,
 				{ sql: deleteSql, params: deleteCompiled.params },
-			];
-
-			await this.#runAtomic(batchStatements, record.name);
+				record.name,
+			);
 			rolled.push(record.name);
 		}
 
@@ -368,6 +532,37 @@ export class MigrationRunner {
 	 * 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.
+	 */
+	async #runStep(
+		statements: string[],
+		deferred: DeferredMigrationCallback[],
+		recordStmt: BatchStmt,
+		migrationName: string,
+	): Promise<void> {
+		const schemaBatch: BatchStmt[] = statements.map((sql) => ({
+			sql,
+			params: [] as unknown[],
+		}));
+		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);
+		}
+		await this.#db.execute(recordStmt.sql, recordStmt.params);
+	}
+
 	async #runAtomic(
 		batch: readonly BatchStmt[],
 		migrationName: string,
@@ -392,32 +587,80 @@ export class MigrationRunner {
 	 *
 	 * @implements Story 32.11
 	 */
-	async refresh(): Promise<{ rolled: string[]; executed: string[] }> {
-		const rolled = await this.reset();
+	async refresh(
+		options: { force?: boolean } = {},
+	): Promise<{ rolled: string[]; executed: string[] }> {
+		const rolled = await this.reset(options);
 		const executed = await this.migrate();
 		return { rolled, executed };
 	}
 
 	/**
-	 * Drop EVERY table the migrations created (via successive rollbacks) then
-	 * run every migration from scratch. `migrate:fresh` in Lucid parlance.
+	 * 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.
 	 *
-	 * Distinct from `refresh()` only in intent — both end up with a fresh DB.
+	 * `rolled` is always empty — fresh drops rather than rolls back.
 	 */
 	async fresh(): Promise<{ rolled: string[]; executed: string[] }> {
-		return this.refresh();
+		await this.#dropAllTables();
+		const executed = await this.migrate();
+		return { rolled: [], executed };
+	}
+
+	/**
+	 * 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.
+	 *
+	 * 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 wipe(): Promise<void> {
+		return this.#dropAllTables();
+	}
+
+	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,
+		});
+		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);
+				}
+			}
+		});
 	}
 
 	/**
 	 * Rollback every applied batch (alias for `migrate:reset`).
 	 * Returns the list of rolled-back migration names (in rollback order).
 	 */
-	async reset(): Promise<string[]> {
+	async reset(options: { force?: boolean } = {}): Promise<string[]> {
+		this.#assertRollbackAllowed(options.force ?? false);
 		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();
+			const rolled = await this.rollback({ force: true });
 			if (rolled.length === 0) break;
 			all.push(...rolled);
 		}
@@ -454,7 +697,7 @@ export class MigrationRunner {
 		for (const name of files) {
 			this.#assertSafeName(name);
 			const migration = await this.#loadMigration(name);
-			const statements = await migration.getUpSQL();
+			const statements = await migration.getUpSQL(this.#db);
 			result.push({ name, sql: statements });
 		}
 		return result;

package/src/schema/Schema.ts

@@ -12,26 +12,146 @@ import {
 	compileStatementNative,
 	getAtlasDialect,
 } from "../query/native.js";
+import {
+	type CatalogConnection,
+	columnExists,
+	tableExists,
+} from "./catalog.js";
 import { TableBuilder } from "./TableBuilder.js";
 
 export class Schema {
 	#dialect: AtlasDialect;
 	#statements: string[] = [];
+	#connection?: CatalogConnection;
+	#schemaName?: string;
 
 	constructor(dialect: AtlasDialect = getAtlasDialect()) {
 		this.#dialect = dialect;
 	}
 
+	/**
+	 * Qualify subsequent table names with `name` (Adonis Lucid/Knex
+	 * `withSchema`), e.g. `withSchema('reporting').createTable('t', …)` targets
+	 * `"reporting"."t"`. Applies to every table-taking method until changed; the
+	 * Rust compiler quotes each dotted segment. Chainable.
+	 */
+	withSchema(name: string): this {
+		this.#schemaName = name;
+		return this;
+	}
+
+	/** Prefix a table name with the active schema, if one was set. */
+	#qualify(table: string): string {
+		return this.#schemaName ? `${this.#schemaName}.${table}` : table;
+	}
+
+	/**
+	 * Attach a live connection so the async introspection helpers
+	 * ({@link hasTable}/{@link hasColumn}) can query the catalog. The migration
+	 * runner calls this before running a migration's `up`/`down`.
+	 */
+	bindConnection(connection: CatalogConnection): void {
+		this.#connection = connection;
+	}
+
+	/**
+	 * Does this table exist right now? (Adonis Lucid/Knex `hasTable`.) Runs a
+	 * live catalog query, so it reflects migrations already applied — but NOT
+	 * statements this same migration has only buffered (they run after `up`).
+	 * Requires a bound connection (present inside a migration).
+	 */
+	async hasTable(name: string): Promise<boolean> {
+		return tableExists(
+			this.#requireConnection("hasTable"),
+			this.#dialect,
+			name,
+		);
+	}
+
+	/** Does this column exist on this table right now? (Adonis Lucid/Knex `hasColumn`.) */
+	async hasColumn(table: string, column: string): Promise<boolean> {
+		return columnExists(
+			this.#requireConnection("hasColumn"),
+			this.#dialect,
+			table,
+			column,
+		);
+	}
+
+	#requireConnection(method: string): CatalogConnection {
+		if (!this.#connection) {
+			throw new Error(
+				`E_NO_CONNECTION: schema.${method}() needs a live connection — it is available inside a migration, not on a standalone Schema.`,
+			);
+		}
+		return this.#connection;
+	}
+
 	createTable(name: string, callback: (table: TableBuilder) => void): this {
-		const builder = new TableBuilder(name);
+		const builder = new TableBuilder(this.#qualify(name));
 		callback(builder);
 		this.#statements.push(...builder.toStatements(this.#dialect));
 		return this;
 	}
 
+	/** `CREATE TABLE IF NOT EXISTS` (Lucid/Knex `createTableIfNotExists`). */
+	createTableIfNotExists(
+		name: string,
+		callback: (table: TableBuilder) => void,
+	): this {
+		const builder = new TableBuilder(this.#qualify(name));
+		callback(builder);
+		this.#statements.push(
+			...builder.toStatements(this.#dialect, { ifNotExists: true }),
+		);
+		return this;
+	}
+
+	/**
+	 * `ALTER TABLE` (Lucid/Knex `alterTable`, also spelled `table()`). Inside
+	 * the callback a column-type method adds a column, `.alter()` changes one,
+	 * and `dropColumn` / `renameColumn` / `setNullable` / `dropNullable` do
+	 * what they say. Operations compile in call order.
+	 */
+	alterTable(name: string, callback: (table: TableBuilder) => void): this {
+		const builder = new TableBuilder(this.#qualify(name), "alter");
+		callback(builder);
+		// An empty callback is a caller bug, not an empty statement list: the
+		// Rust compiler rejects a no-op ALTER, so short-circuit with a clearer error.
+		if (
+			builder.getOperations().length === 0 &&
+			builder.getIndexes().length === 0
+		) {
+			throw new Error(
+				`E_ALTER_EMPTY: schema.alterTable('${name}') declared no operations`,
+			);
+		}
+		this.#statements.push(...builder.toStatements(this.#dialect));
+		return this;
+	}
+
+	/** Alias of {@link alterTable} (Lucid/Knex `table()`). */
+	table(name: string, callback: (table: TableBuilder) => void): this {
+		return this.alterTable(name, callback);
+	}
+
+	/** `ALTER TABLE old RENAME TO new` (Lucid/Knex `renameTable`). */
+	renameTable(from: string, to: string): this {
+		const { statements } = compileStatementNative(
+			{
+				kind: "renameTable",
+				table: this.#qualify(from),
+				to: this.#qualify(to),
+			},
+			this.#dialect,
+		);
+		this.#statements.push(...statements);
+		return this;
+	}
+
 	dropTable(name: string): this {
 		const { statements } = compileStatementNative(
-			{ kind: "dropTable", table: name, ifExists: true },
+			{ kind: "dropTable", table: this.#qualify(name), ifExists: true },
 			this.#dialect,
 		);
 		this.#statements.push(...statements);
@@ -47,7 +167,13 @@ export class Schema {
 		const cols = Array.isArray(columns) ? columns : [columns];
 		const indexName = name ?? `idx_${table}_${cols.join("_")}`;
 		const { statements } = compileStatementNative(
-			{ kind: "createIndex", table, name: indexName, columns: cols, unique },
+			{
+				kind: "createIndex",
+				table: this.#qualify(table),
+				name: indexName,
+				columns: cols,
+				unique,
+			},
 			this.#dialect,
 		);
 		this.#statements.push(...statements);
@@ -63,6 +189,87 @@ export class Schema {
 		return this;
 	}
 
+	/**
+	 * `CREATE VIEW name [(cols)] AS <select>` (Lucid/Knex `createView`). The
+	 * `select` is raw, developer-authored SQL — same trust level as {@link raw} —
+	 * embedded verbatim; the view name and column list are validated + quoted by
+	 * the Rust compiler.
+	 */
+	createView(
+		name: string,
+		select: string,
+		options: { columns?: string[] } = {},
+	): this {
+		return this.#pushView(name, select, options);
+	}
+
+	/** `CREATE OR REPLACE VIEW` (Lucid/Knex `createViewOrReplace`). Rejected on SQLite. */
+	createViewOrReplace(
+		name: string,
+		select: string,
+		options: { columns?: string[] } = {},
+	): this {
+		return this.#pushView(name, select, { ...options, orReplace: true });
+	}
+
+	/** `CREATE MATERIALIZED VIEW` (Lucid/Knex `createMaterializedView`). Postgres-only. */
+	createMaterializedView(
+		name: string,
+		select: string,
+		options: { columns?: string[] } = {},
+	): this {
+		return this.#pushView(name, select, { ...options, materialized: true });
+	}
+
+	/** `DROP VIEW IF EXISTS name` (Lucid/Knex `dropView`/`dropViewIfExists`). */
+	dropView(name: string): this {
+		const { statements } = compileStatementNative(
+			{ kind: "dropView", name: this.#qualify(name), ifExists: true },
+			this.#dialect,
+		);
+		this.#statements.push(...statements);
+		return this;
+	}
+
+	/** `DROP MATERIALIZED VIEW IF EXISTS name` (Lucid/Knex). Postgres-only. */
+	dropMaterializedView(name: string): this {
+		const { statements } = compileStatementNative(
+			{
+				kind: "dropView",
+				name: this.#qualify(name),
+				ifExists: true,
+				materialized: true,
+			},
+			this.#dialect,
+		);
+		this.#statements.push(...statements);
+		return this;
+	}
+
+	#pushView(
+		name: string,
+		select: string,
+		options: {
+			columns?: string[];
+			orReplace?: boolean;
+			materialized?: boolean;
+		},
+	): this {
+		const { statements } = compileStatementNative(
+			{
+				kind: "createView",
+				name: this.#qualify(name),
+				select,
+				orReplace: options.orReplace ?? false,
+				materialized: options.materialized ?? false,
+				columns: options.columns ?? null,
+			},
+			this.#dialect,
+		);
+		this.#statements.push(...statements);
+		return this;
+	}
+
 	raw(sql: string): this {
 		this.#statements.push(sql);
 		return this;