@c9up/atlas 0.1.18 → 0.2.0

package/src/Transaction.ts

@@ -12,30 +12,85 @@ import {
 	TRANSACTION_BRAND,
 } from "./utils/transactionBrand.js";
 
+/** A post-commit / post-rollback side effect (Lucid `trx.after(...)`). */
+export type AfterHook = () => void | Promise<void>;
+
 export interface TransactionClient extends DatabaseConnection {
 	commit(): Promise<void>;
 	rollback(): Promise<void>;
+	/**
+	 * Register a side effect to run AFTER the transaction is durable (Lucid
+	 * `trx.after('commit' | 'rollback', cb)`). A `commit` hook fires only once the
+	 * ROOT transaction commits — inside a nested (SAVEPOINT) transaction it is
+	 * forwarded to the parent, so a later outer rollback never runs it. Errors
+	 * thrown by a hook are swallowed (the caller already saw the transaction
+	 * succeed).
+	 */
+	after(event: "commit" | "rollback", cb: AfterHook): void;
 	readonly isNested: boolean;
 	readonly [TRANSACTION_BRAND]: true;
 }
 
+/**
+ * Run every registered after-hook, swallowing errors — a post-commit side
+ * effect must never surface a failure on a transaction the caller already saw
+ * commit (Lucid parity). Shared with the napi adapter's pinned-transaction path.
+ */
+export async function runAfterHooks(hooks: AfterHook[]): Promise<void> {
+	for (const hook of hooks) {
+		try {
+			await hook();
+		} catch {
+			/* swallowed — the transaction already succeeded */
+		}
+	}
+}
+
 export async function transaction<T>(
 	db: DatabaseConnection,
 	callback: (trx: TransactionClient) => Promise<T> | T,
 	options?: TransactionOptions,
 ): Promise<T> {
 	if (isTransactionClient(db)) {
+		const parent = db;
 		const name = `sp_${randomBytes(6).toString("hex")}`;
-		await db.execute(`SAVEPOINT ${name}`, []);
+		await parent.execute(`SAVEPOINT ${name}`, []);
+
+		const commitHooks: AfterHook[] = [];
+		const rollbackHooks: AfterHook[] = [];
 
 		const trx: TransactionClient = {
-			execute: db.execute.bind(db),
-			query: db.query.bind(db),
+			execute: parent.execute.bind(parent),
+			query: parent.query.bind(parent),
 			async commit() {
-				await db.execute(`RELEASE SAVEPOINT ${name}`, []);
+				await parent.execute(`RELEASE SAVEPOINT ${name}`, []);
+				// A nested commit is NOT durable until the root commits — forward BOTH
+				// hook sets to the parent. Commit hooks fire on the real (root) commit
+				// and drop if the outer later rolls back. Rollback hooks must ALSO
+				// forward: this savepoint's released work is folded into the parent, so
+				// an outer rollback undoes it too — dropping them here would strand any
+				// in-memory restoration a nested caller registered on `after('rollback')`
+				// (the work IS rolled back, just by the parent). The parent fires exactly
+				// one of its two hook sets, so no double-run.
+				for (const hook of commitHooks) parent.after("commit", hook);
+				for (const hook of rollbackHooks) parent.after("rollback", hook);
 			},
 			async rollback() {
-				await db.execute(`ROLLBACK TO SAVEPOINT ${name}`, []);
+				await parent.execute(`ROLLBACK TO SAVEPOINT ${name}`, []);
+				// ROLLBACK TO leaves the savepoint ESTABLISHED — release it so it doesn't
+				// stay stacked on the connection through a long outer transaction with
+				// many nested failures. Best-effort: the rollback already unwound the
+				// work, so a RELEASE failure must not surface. (PG/MySQL/SQLite all
+				// accept RELEASE after ROLLBACK TO.)
+				try {
+					await parent.execute(`RELEASE SAVEPOINT ${name}`, []);
+				} catch {
+					/* best-effort — the savepoint is already logically unwound */
+				}
+				await runAfterHooks(rollbackHooks);
+			},
+			after(event, cb) {
+				(event === "commit" ? commitHooks : rollbackHooks).push(cb);
 			},
 			isNested: true,
 			[TRANSACTION_BRAND]: true,
@@ -68,14 +123,22 @@ export async function transaction<T>(
 
 	await db.execute("BEGIN", []);
 
+	const commitHooks: AfterHook[] = [];
+	const rollbackHooks: AfterHook[] = [];
+
 	const trx: TransactionClient = {
 		execute: db.execute.bind(db),
 		query: db.query.bind(db),
 		async commit() {
 			await db.execute("COMMIT", []);
+			await runAfterHooks(commitHooks);
 		},
 		async rollback() {
 			await db.execute("ROLLBACK", []);
+			await runAfterHooks(rollbackHooks);
+		},
+		after(event, cb) {
+			(event === "commit" ? commitHooks : rollbackHooks).push(cb);
 		},
 		isNested: false,
 		[TRANSACTION_BRAND]: true,

package/src/adapters/NapiDbAdapter.ts

@@ -2,10 +2,51 @@
  * NapiDbAdapter — bridges the Rust atlas-db NAPI binding to Atlas.
  */
 
-import type { TransactionClient } from "../Transaction.js";
+import { emitDbQuery, hasDbQueryListeners } from "../events.js";
+import {
+	type AfterHook,
+	runAfterHooks,
+	type TransactionClient,
+} from "../Transaction.js";
 import { dialectFromUrl } from "../utils/dialectFromUrl.js";
 import { TRANSACTION_BRAND } from "../utils/transactionBrand.js";
 
+/**
+ * JSON replacer for the napi boundary. `BigInt` throws in a plain
+ * `JSON.stringify` and a `Uint8Array`/`Buffer` serializes to a useless
+ * index-map, so both are wrapped in envelopes the Rust side decodes and binds
+ * losslessly: `{"$bigint": "123"}` → i64, `{"$bytes": "<base64>"}` → BLOB/BYTEA.
+ */
+function napiReplacer(_key: string, value: unknown): unknown {
+	if (typeof value === "bigint") return { $bigint: value.toString() };
+	if (value instanceof Uint8Array) {
+		return { $bytes: Buffer.from(value).toString("base64") };
+	}
+	return value;
+}
+
+/**
+ * JSON reviver for napi result sets. Rebuilds `{"$bytes": …}` envelopes (emitted
+ * by the Rust decoder for BLOB/BYTEA columns) into a `Uint8Array`. Integers
+ * beyond JS's safe range arrive pre-stringified by Rust — no precision loss — so
+ * they stay strings, matching the pg/mysql driver convention.
+ */
+function napiReviver(_key: string, value: unknown): unknown {
+	if (
+		typeof value === "object" &&
+		value !== null &&
+		!Array.isArray(value) &&
+		"$bytes" in value &&
+		Object.keys(value).length === 1
+	) {
+		const bytes = value.$bytes;
+		if (typeof bytes === "string") {
+			return Uint8Array.from(Buffer.from(bytes, "base64"));
+		}
+	}
+	return value;
+}
+
 /** One `(sql, params)` pair passed to `runInTransaction`. */
 export interface BatchStatement {
 	sql: string;
@@ -28,6 +69,37 @@ export interface TransactionOptions {
 	isolationLevel?: IsolationLevel;
 }
 
+/**
+ * Context a caller can attach to a statement so the `db:query` event can say
+ * where it came from. Optional everywhere — a connection that ignores it stays
+ * a valid `AsyncDatabaseConnection`, which is what lets test doubles skip it.
+ */
+export interface QueryMeta {
+	/** Entity class name, when the statement came from a repository/model. */
+	model?: string;
+	/** The call that produced it (`exec`, `first`, `paginate`, …). */
+	method?: string;
+	/** True for schema statements. */
+	ddl?: boolean;
+	/**
+	 * Force emission for this statement even when the connection has
+	 * `debug: false` — this is what `ModelQuery.debug()` sets.
+	 */
+	debug?: boolean;
+}
+
+/** Per-connection observability settings (Lucid's `debug` connection option). */
+export interface ObservabilityOptions {
+	/**
+	 * Emit a `db:query` event for every statement on this connection. Off by
+	 * default: it costs a timing pair per query, and nothing is emitted anyway
+	 * unless something subscribed via `onDbQuery`.
+	 */
+	debug?: boolean;
+	/** Connection name, reported on each event so multi-connection apps can tell them apart. */
+	connectionName?: string;
+}
+
 /** Async database connection backed by Rust (sqlx). */
 export interface AsyncDatabaseConnection {
 	/** The dialect this connection targets — derived from the URL scheme at connect time. */
@@ -35,8 +107,13 @@ export interface AsyncDatabaseConnection {
 	query<T = Record<string, unknown>>(
 		sql: string,
 		params?: unknown[],
+		meta?: QueryMeta,
 	): Promise<T[]>;
-	execute(sql: string, params?: unknown[]): Promise<{ rowsAffected: number }>;
+	execute(
+		sql: string,
+		params?: unknown[],
+		meta?: QueryMeta,
+	): Promise<{ rowsAffected: number }>;
 	/**
 	 * Run every statement in `batch` atomically inside a single sqlx transaction.
 	 * Either every statement commits or none do — used by MigrationRunner to
@@ -129,7 +206,9 @@ export async function createNapiConnection(
 	poolMax = 10,
 	pragmas?: Record<string, string | number>,
 	retry?: ConnectRetryOptions,
+	observability: ObservabilityOptions = {},
 ): Promise<AsyncDatabaseConnection> {
+	const { debug = false, connectionName } = observability;
 	// Throws with the underlying cause if the binary can't be loaded.
 	const native = await loadNativeDb();
 
@@ -184,26 +263,41 @@ export async function createNapiConnection(
 		isolationLevel?: IsolationLevel,
 	): Promise<TransactionClient> {
 		const native = await db.begin(isolationLevel);
+		// Root (non-nested) transaction: after-hooks fire once the underlying
+		// COMMIT / ROLLBACK is durable (Lucid `trx.after(...)`), errors swallowed.
+		const commitHooks: AfterHook[] = [];
+		const rollbackHooks: AfterHook[] = [];
 		return {
 			async execute(
 				sql: string,
 				params: unknown[] = [],
 			): Promise<{ rowsAffected: number }> {
-				const affected = await native.execute(sql, JSON.stringify(params));
+				const affected = await native.execute(
+					sql,
+					JSON.stringify(params, napiReplacer),
+				);
 				return { rowsAffected: affected };
 			},
 			async query<T = Record<string, unknown>>(
 				sql: string,
 				params: unknown[] = [],
 			): Promise<T[]> {
-				const json = await native.query(sql, JSON.stringify(params));
-				return JSON.parse(json) as T[];
+				const json = await native.query(
+					sql,
+					JSON.stringify(params, napiReplacer),
+				);
+				return JSON.parse(json, napiReviver) as T[];
 			},
 			async commit(): Promise<void> {
 				await native.commit();
+				await runAfterHooks(commitHooks);
 			},
 			async rollback(): Promise<void> {
 				await native.rollback();
+				await runAfterHooks(rollbackHooks);
+			},
+			after(event: "commit" | "rollback", cb: AfterHook): void {
+				(event === "commit" ? commitHooks : rollbackHooks).push(cb);
 			},
 			isNested: false,
 			[TRANSACTION_BRAND]: true,
@@ -240,29 +334,84 @@ export async function createNapiConnection(
 		}
 	}
 
+	/**
+	 * Run `fn`, emitting a `db:query` event around it when observation is on.
+	 *
+	 * The fast path is a single boolean pair: with no listeners, or with debug
+	 * off and no per-query override, this adds nothing but the check. The event
+	 * is emitted on failure too — a slow query that then throws is exactly the
+	 * one worth seeing.
+	 */
+	async function observed<T>(
+		sql: string,
+		params: unknown[],
+		meta: QueryMeta | undefined,
+		fn: () => Promise<T>,
+	): Promise<T> {
+		if (!(debug || meta?.debug) || !hasDbQueryListeners()) return fn();
+
+		const startedAt = performance.now();
+		try {
+			const result = await fn();
+			emitDbQuery({
+				sql,
+				bindings: params,
+				duration: performance.now() - startedAt,
+				connection: connectionName,
+				model: meta?.model,
+				method: meta?.method,
+				ddl: meta?.ddl,
+				inTransaction: false,
+			});
+			return result;
+		} catch (error) {
+			emitDbQuery({
+				sql,
+				bindings: params,
+				duration: performance.now() - startedAt,
+				connection: connectionName,
+				model: meta?.model,
+				method: meta?.method,
+				ddl: meta?.ddl,
+				inTransaction: false,
+				error: error instanceof Error ? error : new Error(String(error)),
+			});
+			throw error;
+		}
+	}
+
 	return {
 		dialect,
 		transaction,
 		async query<T = Record<string, unknown>>(
 			sql: string,
 			params: unknown[] = [],
+			meta?: QueryMeta,
 		): Promise<T[]> {
-			const json = await db.query(sql, JSON.stringify(params));
-			return JSON.parse(json) as T[];
+			return observed(sql, params, meta, async () => {
+				const json = await db.query(sql, JSON.stringify(params, napiReplacer));
+				return JSON.parse(json, napiReviver) as T[];
+			});
 		},
 
 		async execute(
 			sql: string,
 			params: unknown[] = [],
+			meta?: QueryMeta,
 		): Promise<{ rowsAffected: number }> {
-			const affected = await db.execute(sql, JSON.stringify(params));
-			return { rowsAffected: affected };
+			return observed(sql, params, meta, async () => {
+				const affected = await db.execute(
+					sql,
+					JSON.stringify(params, napiReplacer),
+				);
+				return { rowsAffected: affected };
+			});
 		},
 
 		async runInTransaction(batch: readonly BatchStatement[]): Promise<number> {
 			// Rust side expects `[[sql, params], ...]`
 			const payload = batch.map((s) => [s.sql, s.params ?? []]);
-			return db.runInTransaction(JSON.stringify(payload));
+			return db.runInTransaction(JSON.stringify(payload, napiReplacer));
 		},
 
 		async close(): Promise<void> {

package/src/console/migrationCommands.ts

@@ -0,0 +1,258 @@
+/**
+ * Migration console commands — the Ream-idiomatic CLI for running, rolling back,
+ * inspecting, and wiping migrations. Same shape and contract as
+ * {@link schemaCheckCommand}: plain `{ name, description, run }` objects
+ * registered in `reamrc.commands` and dispatched by the console kernel.
+ *
+ * Each command resolves the live connection from atlas's OWN service locator
+ * (`getDb`), never importing `@c9up/ream`, and drives the already-tested
+ * {@link MigrationRunner}. Atlas has no global config registry (Lucid parity —
+ * you pass your own paths), so every factory takes the `migrationsDir`.
+ *
+ * @example
+ *   // commands/migrate.ts
+ *   import { migrationRunCommand } from '@c9up/atlas'
+ *   export default migrationRunCommand({ migrationsDir: 'database/migrations' })
+ *
+ *   // reamrc.ts → commands: [() => import('./commands/migrate.js')]
+ *   // run:  <console-entry> migration:run
+ */
+
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
+import {
+	type DatabaseAdapter,
+	MigrationRunner,
+} from "../schema/MigrationRunner.js";
+import { getDb } from "../services/db.js";
+import { assertSafeName } from "../utils/safePath.js";
+import type { AtlasCommand } from "./schemaCheckCommand.js";
+
+export interface MigrationCommandOptions {
+	/** Directory holding the numbered migration files. */
+	migrationsDir: string;
+}
+
+/**
+ * Adapt the shared singleton connection to the runner's {@link DatabaseAdapter}.
+ * `close()` is intentionally a no-op — the console kernel owns the connection's
+ * lifecycle, so a command must not tear down a connection other commands share.
+ */
+function toAdapter(conn: AsyncDatabaseConnection): DatabaseAdapter {
+	return {
+		execute: async (sql, params) => {
+			await conn.execute(sql, params);
+		},
+		query: (sql, params) => conn.query(sql, params),
+		runInTransaction: (batch) => conn.runInTransaction(batch),
+		close: async () => {},
+	};
+}
+
+/**
+ * Resolve a runner from the live connection, or report and set a failing exit
+ * code when no connection is registered (mirrors `schemaCheckCommand`).
+ */
+function resolveRunner(
+	options: MigrationCommandOptions,
+): MigrationRunner | undefined {
+	const db = getDb();
+	if (!db) {
+		console.error(
+			"[atlas] no database connection — is AtlasProvider registered?",
+		);
+		process.exitCode = 1;
+		return undefined;
+	}
+	return new MigrationRunner(toAdapter(db), {
+		migrationsDir: options.migrationsDir,
+	});
+}
+
+/** `migration:run` — apply every pending migration. */
+export function migrationRunCommand(
+	options: MigrationCommandOptions,
+): AtlasCommand {
+	return {
+		name: "migration:run",
+		description: "Run all pending migrations",
+		async run() {
+			const runner = resolveRunner(options);
+			if (!runner) return;
+			const ran = await runner.migrate();
+			console.log(
+				ran.length ? `Migrated: ${ran.join(", ")}` : "Already up to date",
+			);
+		},
+	};
+}
+
+/**
+ * `migration:rollback` — undo the latest batch, or with `--batch=N` roll back
+ * everything applied after batch N (`--batch=0` rolls back all).
+ */
+export function migrationRollbackCommand(
+	options: MigrationCommandOptions,
+): AtlasCommand {
+	return {
+		name: "migration:rollback",
+		description: "Roll back the latest batch (or --batch=N)",
+		async run(_args, flags) {
+			const runner = resolveRunner(options);
+			if (!runner) return;
+			const batch = parseBatchFlag(flags.batch);
+			if (batch === "invalid") {
+				console.error("[atlas] --batch must be a non-negative integer");
+				process.exitCode = 1;
+				return;
+			}
+			const rolled = await runner.rollback(
+				batch === undefined ? {} : { batch },
+			);
+			console.log(
+				rolled.length
+					? `Rolled back: ${rolled.join(", ")}`
+					: "Nothing to roll back",
+			);
+		},
+	};
+}
+
+/** `migration:status` — list every migration and whether it is applied. */
+export function migrationStatusCommand(
+	options: MigrationCommandOptions,
+): AtlasCommand {
+	return {
+		name: "migration:status",
+		description: "Show applied and pending migrations",
+		async run() {
+			const runner = resolveRunner(options);
+			if (!runner) return;
+			const rows = await runner.status();
+			if (rows.length === 0) {
+				console.log("No migrations found");
+				return;
+			}
+			for (const row of rows) {
+				const batch = row.batch === undefined ? "" : ` (batch ${row.batch})`;
+				console.log(`${row.status.padEnd(8)} ${row.name}${batch}`);
+			}
+		},
+	};
+}
+
+/** `migration:reset` — roll back every applied migration. */
+export function migrationResetCommand(
+	options: MigrationCommandOptions,
+): AtlasCommand {
+	return {
+		name: "migration:reset",
+		description: "Roll back all migrations",
+		async run() {
+			const runner = resolveRunner(options);
+			if (!runner) return;
+			const rolled = await runner.reset();
+			console.log(
+				rolled.length
+					? `Rolled back: ${rolled.join(", ")}`
+					: "Nothing to reset",
+			);
+		},
+	};
+}
+
+/** `migration:refresh` — roll everything back, then re-run all migrations. */
+export function migrationRefreshCommand(
+	options: MigrationCommandOptions,
+): AtlasCommand {
+	return {
+		name: "migration:refresh",
+		description: "Roll back all migrations, then re-run them",
+		async run() {
+			const runner = resolveRunner(options);
+			if (!runner) return;
+			const { rolled, executed } = await runner.refresh();
+			console.log(`Rolled back: ${rolled.length}, re-ran: ${executed.length}`);
+		},
+	};
+}
+
+/** `db:wipe` — drop every table, including the migrations bookkeeping table. */
+export function dbWipeCommand(options: MigrationCommandOptions): AtlasCommand {
+	return {
+		name: "db:wipe",
+		description: "Drop all tables (including the migrations table)",
+		async run() {
+			const runner = resolveRunner(options);
+			if (!runner) return;
+			await runner.wipe();
+			console.log("Dropped all tables");
+		},
+	};
+}
+
+/** Scaffold body for a fresh migration (`make:migration`). */
+const MIGRATION_STUB = `import { Migration } from '@c9up/atlas'
+
+export default class extends Migration {
+  async up() {
+    // this.schema.createTable('table_name', (table) => {
+    //   table.increments('id')
+    // })
+  }
+
+  async down() {
+    // this.schema.dropTable('table_name')
+  }
+}
+`;
+
+/**
+ * `make:migration <name>` — scaffold a timestamped migration file in
+ * `migrationsDir`. The `Date.now()` prefix keeps files in creation order under
+ * the runner's lexicographic sort (same convention as AdonisJS/Lucid). The name
+ * is validated (no path separators / traversal) and the file is written with
+ * `wx` so an existing migration is never clobbered.
+ */
+export function makeMigrationCommand(
+	options: MigrationCommandOptions,
+): AtlasCommand {
+	return {
+		name: "make:migration",
+		description: "Scaffold a new timestamped migration file",
+		async run(args) {
+			const name = args[0];
+			if (!name) {
+				console.error("[atlas] usage: make:migration <name>");
+				process.exitCode = 1;
+				return;
+			}
+			try {
+				assertSafeName(name, "MIGRATION_INVALID", "migration");
+			} catch {
+				console.error(`[atlas] invalid migration name: ${name}`);
+				process.exitCode = 1;
+				return;
+			}
+			const fileName = `${Date.now()}_${name}.ts`;
+			const filePath = path.join(options.migrationsDir, fileName);
+			await fsp.mkdir(options.migrationsDir, { recursive: true });
+			await fsp.writeFile(filePath, MIGRATION_STUB, { flag: "wx" });
+			console.log(`Created ${filePath}`);
+		},
+	};
+}
+
+/**
+ * Parse the `--batch` flag: absent → undefined (default rollback), a
+ * non-negative integer string → that number, anything else → `"invalid"`.
+ */
+function parseBatchFlag(
+	value: string | boolean | undefined,
+): number | undefined | "invalid" {
+	if (value === undefined || value === true) return undefined;
+	if (value === false) return "invalid";
+	const n = Number(value);
+	return Number.isInteger(n) && n >= 0 ? n : "invalid";
+}