bunsql-native-migrate 0.1.1 → 0.2.0

package/README.md

@@ -5,14 +5,15 @@
 
 Zero-ORM SQL file migrations for [Bun](https://bun.sh): PostgreSQL, MySQL/MariaDB and SQLite through the built-in `Bun.SQL` client.
 
-No ORM, no schema diffing, no lock-in — you write plain `.js` migration files with `up()`/`down()` exports and run them with a tiny CLI or the programmatic API.
+No ORM, no schema diffing, no lock-in — you write plain `.js`/`.ts` migration files with `up()`/`down()` exports (optionally `up(tx)`/`down(tx)` for transactional migrations, see below) and run them with a tiny CLI or the programmatic API.
 
 ## Features
 
 - **Bun-native** — built on the unified [`Bun.SQL`](https://bun.com/docs/runtime/sql) client (PostgreSQL, MySQL/MariaDB, SQLite). No Node.js support.
-- **Zero ORM** — migrations are plain JavaScript files; use `sql` tagged templates or any Bun database client you like.
+- **Zero ORM** — migrations are plain JavaScript or TypeScript files; use `sql` tagged templates or any Bun database client you like.
 - **Zero dependencies**.
 - **Checksums** — every applied migration is checksummed (SHA-256). A modified applied file fails the run instead of silently drifting.
+- **Concurrent-safe `up`** — an advisory database lock serializes racing `up` runs (two deploy pods, CI + laptop) so a migration body never executes twice.
 - **Legacy backfill** — records without a checksum are backfilled automatically on the next `up`.
 - **CLI and library** — use it as `bunx bunsql-native-migrate` or import the functions directly.
 
@@ -27,7 +28,7 @@ Requires Bun ≥ 1.4.2 — the version this package is developed and tested agai
 ## Quick start
 
 ```bash
-# create migrations/<timestamp>_<name>.js from the stub template
+# create migrations/<timestamp>_<name>.ts from the stub template
 bunx bunsql-native-migrate create add_users_table
 
 # create the tracking table (optional — up() does it automatically)
@@ -36,6 +37,12 @@ bunx bunsql-native-migrate install
 # apply pending migrations
 bunx bunsql-native-migrate up
 
+# see what is applied and what is pending
+bunx bunsql-native-migrate status
+
+# CI gate: same listing, but exit code 1 while migrations are pending
+bunx bunsql-native-migrate status --strict
+
 # roll back the last applied migration
 bunx bunsql-native-migrate down
 ```
@@ -58,12 +65,34 @@ const down = async () => {
 export { up, down };
 ```
 
-Files live in the migrations directory (default `./migrations`, override with `--dir` or the `MIGRATION_LIST_DIR` env var) and are applied in descending filename order. `bunsql-native-migrate create` generates names with an inverted timestamp prefix so newer migrations sort first:
+Files live in the migrations directory (default `./migrations`, override with `--dir` or the `MIGRATION_LIST_DIR` env var) and are applied in descending filename order. Both `.js` and `.ts` files work — Bun runs TypeScript natively — and the order is decided purely by the filename, never by the extension. `bunsql-native-migrate create` generates TypeScript stubs by default (`--lang js` for JavaScript) with an inverted timestamp prefix so newer migrations sort first:
 
 ```
-9999999999999_2026_09_13_add_users_table.js
+9999999999999_2026_09_13_add_users_table.ts
+```
+
+### Transactional migrations
+
+Declare a `tx` parameter on `up`/`down` and the migration runs inside a single database transaction: if any statement fails, the partial work is rolled back instead of being left half-applied, and nothing is recorded.
+
+```js
+const up = async (tx) => {
+  await tx`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)`;
+  await tx`INSERT INTO users (id, name) VALUES (1, 'admin')`;
+};
+
+const down = async (tx) => {
+  await tx`DROP TABLE users`;
+};
+
+export { up, down };
 ```
 
+- `bunsql-native-migrate create` generates stubs in this form by default (as TypeScript, with `tx` typed as a Bun `SQL` client bound to the same database the runner is connected to).
+- Migrations declared **without** parameters keep using the global `sql` client and run without a transaction — both styles can coexist in one project, decided per migration by the declared signature.
+- Engine caveats: PostgreSQL and SQLite roll back everything, DDL included. On MySQL/MariaDB any DDL statement implicitly commits the current transaction, so there only DML gets rollback protection.
+- The tracking record is written right after the transaction commits. A crash in that single-statement window leaves the migration applied but unrecorded — the next `up` would re-run it, so keep critical migrations idempotent (this window exists for plain `up()` migrations too, just wider).
+
 ### Migrations directory path resolution
 
 Relative paths — whether from `--dir`, the `listDir` option or `MIGRATION_LIST_DIR` — are always resolved against the **current working directory** of the process (the same anchor Bun uses to load `.env`). Run the CLI from your project root and plain `./migrations` works as expected.
@@ -79,21 +108,27 @@ This resolution is part of the library contract: `resolveListDir` (and therefore
 ## CLI reference
 
 ```
-bunsql-native-migrate <up|down|install|create [name]> [--dir <migrations-dir>] [--git] [--help]
+bunsql-native-migrate <up|down [n]|install|create [name]|status> [--dir <migrations-dir>] [--to <name>] [--lock-timeout <seconds>] [--all] [--lang <js|ts>] [--git] [--strict] [--help]
 ```
 
-| Command         | What it does                                                                                                                        |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `up`            | Applies pending migrations (creating the tracking table if needed); prints `No pending migrations.` when there is nothing to apply. |
-| `down`          | Reverts the last applied migration; prints `No migrations to rollback.` when there is none.                                         |
-| `install`       | Creates the tracking table only.                                                                                                    |
-| `create [name]` | Creates a stub migration file from the template; without a `name` a random `adjective_noun` is generated.                           |
-
-| Flag                     | Applies to | Meaning                                                                                                              |
-| ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------- |
-| `--dir <migrations-dir>` | all        | Migrations directory (default `./migrations`, or the `MIGRATION_LIST_DIR` env var).                                  |
-| `--git`                  | `create`   | `git add` the created file. When staging fails, the CLI prints an error and exits 1 — the file itself stays on disk. |
-| `--help`, `-h`           | —          | Prints the usage line and exits with code 0.                                                                         |
+| Command         | What it does                                                                                                                                                                                                                |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `up`            | Applies pending migrations (creating the tracking table if needed); prints `No pending migrations.` when there is nothing to apply. `up --to <name>` applies pending migrations in order up to and including the named one. |
+| `down`          | Reverts the last applied migration; `down <n>` reverts the last `n`, `down --all` reverts everything — always most-recent-first. Prints `No migrations to rollback.` when there is none.                                    |
+| `install`       | Creates the tracking table only.                                                                                                                                                                                            |
+| `create [name]` | Creates a stub migration file from the template — TypeScript by default, `--lang js` for JavaScript; without a `name` a random `adjective_noun` is generated.                                                               |
+| `status`        | Lists applied and pending migrations (no changes to the database except creating the tracking table if missing) and prints an `N applied, M pending` summary.                                                               |
+
+| Flag                     | Applies to | Meaning                                                                                                                                         |
+| ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--dir <migrations-dir>` | all        | Migrations directory (default `./migrations`, or the `MIGRATION_LIST_DIR` env var).                                                             |
+| `--to <name>`            | `up`       | Apply pending migrations up to and including the named file. An unknown name is an error (exit 1); a target that is already applied is a no-op. |
+| `--lock-timeout <sec>`   | `up`       | How long to wait for the migration lock when another `up` is running, in seconds (default `30`, `0` fails immediately). On timeout: exit 1.     |
+| `--all`                  | `down`     | Revert every applied migration (most-recent-first). Cannot be combined with a step count.                                                       |
+| `--git`                  | `create`   | `git add` the created file. When staging fails, the CLI prints an error and exits 1 — the file itself stays on disk.                            |
+| `--lang <js\|ts>`        | `create`   | Language of the created stub. Default: `ts`. An unknown or missing value is an error (exit 1).                                                  |
+| `--strict`               | `status`   | Exit with code 1 when migrations are pending — a gate for CI/CD pipelines. Exit 0 otherwise.                                                    |
+| `--help`, `-h`           | —          | Prints the usage line and exits with code 0.                                                                                                    |
 
 Any failure (connection errors, a failing migration, a modified applied file) is printed and the CLI exits with code 1; the same happens for an unknown command or a call without a command.
 
@@ -103,19 +138,30 @@ Any failure (connection errors, a failing migration, a modified applied file) is
 import {
   migrateUp,
   migrateDown,
+  migrateStatus,
   installMigrations,
   createMigration,
   createDriver,
   ChecksumDriftError,
+  MigrationLockError,
+  MigrationNotFoundError,
   GitStageError,
 } from "bunsql-native-migrate";
 
 const { applied } = await migrateUp({
   databaseUrl: "postgres://user:pass@localhost:5432/app", // default: DATABASE_URL env
   listDir: "./migrations", // default: MIGRATION_LIST_DIR env or ./migrations
+  to: "2_add_columns.ts", // optional: apply up to and including this file
+  lockTimeout: 60, // optional: seconds to wait for the migration lock (default 30, 0 = fail fast)
 });
 
-const { reverted } = await migrateDown(); // reverted: string | null
+const { reverted } = await migrateDown(); // reverted: string[] (most-recent-first)
+await migrateDown({ steps: 3 }); // revert the last three
+await migrateDown({ steps: "all" }); // revert everything
+
+const status = await migrateStatus();
+// status.applied: ExecutedMigration[] (name + checksum, in apply order)
+// status.pending: string[] (files waiting to be applied, in apply order)
 
 await installMigrations(); // creates the tracking table
 
@@ -124,12 +170,18 @@ const filename = await createMigration({ name: "add_users_table", listDir: "./mi
 
 All options are optional unless stated otherwise:
 
-| Option        | Where                                           | Default                                                                                            |
-| ------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `databaseUrl` | `migrateUp`, `migrateDown`, `installMigrations` | `DATABASE_URL` env var                                                                             |
-| `listDir`     | all functions                                   | `MIGRATION_LIST_DIR` env var, then `./migrations` (relative paths resolve against the process cwd) |
-| `name`        | `createMigration`                               | random `adjective_noun` name                                                                       |
-| `git`         | `createMigration`                               | `false` — `git add` the new file                                                                   |
+| Option        | Where                                                            | Default                                                                                                                                                            |
+| ------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `databaseUrl` | `migrateUp`, `migrateDown`, `migrateStatus`, `installMigrations` | `DATABASE_URL` env var                                                                                                                                             |
+| `listDir`     | all functions                                                    | `MIGRATION_LIST_DIR` env var, then `./migrations` (relative paths resolve against the process cwd)                                                                 |
+| `to`          | `migrateUp`                                                      | — apply pending migrations in order up to and including the named file; an unknown name throws `MigrationNotFoundError`, an already-applied target applies nothing |
+| `lockTimeout` | `migrateUp`                                                      | `30` — seconds to wait for the migration lock while another `up` is running; `0` fails immediately; a timeout throws `MigrationLockError`                          |
+| `steps`       | `migrateDown`                                                    | `1` — revert the last `n` applied migrations (`1`–`n` or `"all"`), most-recent-first                                                                               |
+| `name`        | `createMigration`                                                | random `adjective_noun` name                                                                                                                                       |
+| `lang`        | `createMigration`                                                | `"ts"` — pass `"js"` for a JavaScript stub                                                                                                                         |
+| `git`         | `createMigration`                                                | `false` — `git add` the new file                                                                                                                                   |
+
+`migrateDown` reverts strictly in reverse apply order and stops at the first failing rollback: migrations reverted before the failure stay reverted, the failing one keeps its tracking record, and the error propagates to the caller.
 
 ### Drivers
 
@@ -147,7 +199,7 @@ Known MySQL/MariaDB limitation of `Bun.SQL` (not used by this package, good to k
 
 Bun's client also recognizes `mysql2://` and `file://` URLs — `createDriver` deliberately rejects them. Stick to the protocols listed above.
 
-`createDriver(url)` returns a `MigrationDriver` (`install`/`listExecuted`/`record`/`setChecksum`/`remove`/`close`) if you need custom tracking logic; `listExecuted` yields `ExecutedMigration` records (`name`, `checksum`).
+`createDriver(url)` returns a `MigrationDriver` (`install`/`listExecuted`/`record`/`setChecksum`/`remove`/`close`) if you need custom tracking logic; `listExecuted` yields `ExecutedMigration` records (`name`, `checksum`). Custom drivers may also implement the optional `tryLock(timeoutSeconds)` / `releaseLock()` pair to participate in [concurrent-run locking](#concurrent-runs) — without them, `migrateUp` simply runs unlocked.
 
 ### Tracking table
 
@@ -159,9 +211,19 @@ Applied migrations are recorded in a `migrations` table with a unique name and a
 
 Records created before checksums existed (checksum `NULL`) are backfilled on the next `up`.
 
+### Concurrent runs
+
+Two `up` runs racing (two deploy pods, CI and a laptop) deduplicate only the tracking record against each other — without a lock both would read the same pending list and execute the migration bodies twice. `migrateUp` therefore takes an exclusive database-level lock right after creating the tracking table and holds it until the run ends. The lock is released through a `finally` path on any failure, and it dies with the connection even on a crashed process:
+
+- **PostgreSQL** — session advisory lock (`pg_try_advisory_lock` / `pg_advisory_unlock`) on a reserved connection, keyed per database.
+- **MySQL/MariaDB** — `GET_LOCK` / `RELEASE_LOCK` on a reserved connection, named per database.
+- **SQLite** — there is no advisory lock; the connection gets `PRAGMA busy_timeout`, so a concurrent run waits on the file write lock and fails with a busy error once the timeout is exceeded. The database file itself is the serialization point.
+
+While the lock is held, another `up` polls and waits up to `lockTimeout` seconds (default `30`, CLI `up --lock-timeout <seconds>`, `0` fails immediately). When the wait times out, `migrateUp` throws `MigrationLockError` and the CLI exits with code 1 — rerun after the first run finishes; a waiter that gets through just reports `No pending migrations.`
+
 ### Error handling
 
-The library throws instead of exiting: connection errors, failing migrations and [`ChecksumDriftError`](#tracking-table) propagate to the caller, and the driver connection is always closed. The CLI catches these and exits with code 1.
+The library throws instead of exiting: connection errors, failing migrations, [`ChecksumDriftError`](#tracking-table), `MigrationNotFoundError` (an unknown `to` target, thrown before anything is applied) and [`MigrationLockError`](#concurrent-runs) (another `up` held the lock past `lockTimeout`) propagate to the caller, and the driver connection is always closed. The CLI catches these and exits with code 1.
 
 `createMigration` with `git: true` throws `GitStageError` when `git add` fails (no repository, ignored path, …) — the migration file itself is still created on disk.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunsql-native-migrate",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Zero-ORM SQL file migrations for Bun: PostgreSQL, MySQL/MariaDB and SQLite through the built-in Bun.SQL client",
   "keywords": [
     "bun",

package/src/api/create.ts

@@ -5,22 +5,39 @@ import { resolveListDir } from "../core/fs.js";
 import { log } from "../core/console.js";
 import { GitStageError } from "./options.js";
 
+export type MigrationLang = "js" | "ts";
+
 export interface CreateOptions {
   name?: string;
   git?: boolean;
+  lang?: MigrationLang;
   listDir: string;
 }
 
-const STUB_TEMPLATE = `import { sql } from "bun";
-// Write your migration SQL here
-const up = async () => {};
+const JS_TEMPLATE = `import { sql } from "bun";
+// Write your migration SQL here (tx runs inside a transaction)
+const up = async (tx) => {};
 
 // Write your rollback SQL here
-const down = async () => {};
+const down = async (tx) => {};
 
 export { up, down };
 `;
 
+const TS_TEMPLATE = `import { sql, type SQL } from "bun";
+// Write your migration SQL here (tx runs inside a transaction)
+const up = async (tx: SQL) => {};
+
+// Write your rollback SQL here
+const down = async (tx: SQL) => {};
+
+export { up, down };
+`;
+
+function stubTemplate(lang: MigrationLang): string {
+  return lang === "js" ? JS_TEMPLATE : TS_TEMPLATE;
+}
+
 async function stageInGit(filePath: string): Promise<void> {
   const add = Bun.spawn({
     cmd: ["git", "add", filePath],
@@ -34,7 +51,7 @@ async function stageInGit(filePath: string): Promise<void> {
   }
 }
 
-function migrationFilename(name: string, date: Date): string {
+function migrationFilename(name: string, date: Date, lang: MigrationLang): string {
   const pad = (value: number) => (value <= 9 ? `0${value}` : `${value}`);
   const MAX_TIME = 9999999999999;
   const invertedTime = (MAX_TIME - date.getTime()).toString().padStart(13, "0");
@@ -44,10 +61,10 @@ function migrationFilename(name: string, date: Date): string {
     pad(date.getUTCMonth() + 1),
     pad(date.getUTCDate()),
   ].join("_");
-  return `${timestamp}_${name}.js`;
+  return `${timestamp}_${name}.${lang}`;
 }
 
-async function writeStubExclusively(filePath: string): Promise<boolean> {
+async function writeStubExclusively(filePath: string, template: string): Promise<boolean> {
   let handle: FileHandle;
   try {
     handle = await open(filePath, "wx");
@@ -58,7 +75,7 @@ async function writeStubExclusively(filePath: string): Promise<boolean> {
     throw error;
   }
   try {
-    await handle.writeFile(STUB_TEMPLATE);
+    await handle.writeFile(template);
   } finally {
     await handle.close();
   }
@@ -67,12 +84,13 @@ async function writeStubExclusively(filePath: string): Promise<boolean> {
 
 export async function createMigration(options: CreateOptions): Promise<string> {
   const name = options.name ?? randomName();
+  const lang = options.lang ?? "ts";
   await mkdir(options.listDir, { recursive: true });
-  let filename = migrationFilename(name, new Date());
+  let filename = migrationFilename(name, new Date(), lang);
   let filePath = path.join(options.listDir, filename);
-  while (!(await writeStubExclusively(filePath))) {
+  while (!(await writeStubExclusively(filePath, stubTemplate(lang)))) {
     await Bun.sleep(1);
-    filename = migrationFilename(name, new Date());
+    filename = migrationFilename(name, new Date(), lang);
     filePath = path.join(options.listDir, filename);
   }
 

package/src/api/down.ts

@@ -1,32 +1,58 @@
 import path from "node:path";
 import { resolveListDir } from "../core/fs.js";
 import { log } from "../core/console.js";
-import type { MigrateDownResult, MigrateOptions } from "./options.js";
+import type { MigrationDriver } from "../core/driver.js";
+import type { MigrateDownOptions, MigrateDownResult } from "./options.js";
 import { runWithDriver } from "./run-with-driver.js";
+import { runMigrationStep } from "./run-step.js";
 
-export async function migrateDown(options: MigrateOptions = {}): Promise<MigrateDownResult> {
+function resolveStepCount(steps: number | "all" | undefined, appliedCount: number): number {
+  if (steps === undefined) return 1;
+  if (steps === "all") return appliedCount;
+  if (!Number.isInteger(steps) || steps < 1) {
+    throw new Error(`Invalid steps: ${String(steps)} — expected a positive integer or "all"`);
+  }
+  return steps;
+}
+
+async function revertOne(driver: MigrationDriver, listDir: string, file: string): Promise<void> {
+  const mod = await import(path.join(listDir, file));
+
+  if (typeof mod.down !== "function") {
+    log({ text: `${file} has no down() export, removing tracking record`, type: "warn" });
+    await driver.remove(file);
+    log({ text: `${file} tracking record removed`, type: "success" });
+    return;
+  }
+
+  await runMigrationStep(driver, mod.down);
+  await driver.remove(file);
+  log({ text: `${file} rolled back`, type: "success" });
+}
+
+export async function migrateDown(options: MigrateDownOptions = {}): Promise<MigrateDownResult> {
   const listDir = resolveListDir(options.listDir);
 
   return runWithDriver(options, async (driver) => {
     const executed = await driver.listExecuted();
     if (executed.length === 0) {
       log({ text: "No migrations to rollback.", type: "warn" });
-      return { reverted: null };
+      return { reverted: [] };
     }
 
-    const file = executed[executed.length - 1]!.name;
-    const mod = await import(path.join(listDir, file));
+    const count = resolveStepCount(options.steps, executed.length);
+    const reverted: string[] = [];
 
-    if (typeof mod.down !== "function") {
-      log({ text: `${file} has no down() export, removing tracking record`, type: "warn" });
-      await driver.remove(file);
-      log({ text: `${file} tracking record removed`, type: "success" });
-      return { reverted: file };
+    for (const entry of executed.slice(-count).reverse()) {
+      try {
+        await revertOne(driver, listDir, entry.name);
+      } catch (error) {
+        log({ text: `${entry.name} rollback failed`, type: "error", error });
+        throw error;
+      }
+      reverted.push(entry.name);
     }
 
-    await mod.down();
-    await driver.remove(file);
-    log({ text: `${file} rolled back`, type: "success" });
-    return { reverted: file };
+    return { reverted };
   });
 }

package/src/api/lock.ts

@@ -0,0 +1,50 @@
+import { log } from "../core/console.js";
+import type { MigrationDriver } from "../core/driver.js";
+import { MigrationLockError } from "./options.js";
+
+export const DEFAULT_LOCK_TIMEOUT_SECONDS = 30;
+
+const LOCK_RETRY_DELAY_MS = 100;
+
+export function resolveLockTimeout(lockTimeout: number | undefined): number {
+  if (lockTimeout === undefined) return DEFAULT_LOCK_TIMEOUT_SECONDS;
+  if (!Number.isInteger(lockTimeout) || lockTimeout < 0) {
+    throw new Error(
+      `Invalid lockTimeout: ${String(lockTimeout)} — expected a non-negative integer of seconds`,
+    );
+  }
+  return lockTimeout;
+}
+
+export async function withMigrationLock<T>(
+  driver: MigrationDriver,
+  timeoutSeconds: number,
+  run: () => Promise<T>,
+): Promise<T> {
+  const { tryLock, releaseLock } = driver;
+  if (tryLock === undefined || releaseLock === undefined) {
+    return run();
+  }
+
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let waitingLogged = false;
+  while (!(await tryLock(timeoutSeconds))) {
+    if (Date.now() >= deadline) {
+      throw new MigrationLockError(timeoutSeconds);
+    }
+    if (!waitingLogged) {
+      log({ text: "another migrate up holds the lock — waiting", type: "info" });
+      waitingLogged = true;
+    }
+    await Bun.sleep(LOCK_RETRY_DELAY_MS);
+  }
+
+  try {
+    const result = await run();
+    await releaseLock();
+    return result;
+  } catch (error) {
+    await releaseLock().catch(() => undefined);
+    throw error;
+  }
+}

package/src/api/options.ts

@@ -1,14 +1,30 @@
+import type { ExecutedMigration } from "../core/driver.js";
+
 export interface MigrateOptions {
   databaseUrl?: string;
   listDir?: string;
 }
 
+export interface MigrateUpOptions extends MigrateOptions {
+  to?: string;
+  lockTimeout?: number;
+}
+
+export interface MigrateDownOptions extends MigrateOptions {
+  steps?: number | "all";
+}
+
 export interface MigrateUpResult {
   applied: string[];
 }
 
 export interface MigrateDownResult {
-  reverted: string | null;
+  reverted: string[];
+}
+
+export interface MigrateStatusResult {
+  applied: ExecutedMigration[];
+  pending: string[];
 }
 
 export class ChecksumDriftError extends Error {
@@ -23,6 +39,28 @@ export class ChecksumDriftError extends Error {
   }
 }
 
+export class MigrationNotFoundError extends Error {
+  readonly file: string;
+
+  constructor(file: string) {
+    super(`${file} is not in the migrations directory — nothing was applied`);
+    this.name = "MigrationNotFoundError";
+    this.file = file;
+  }
+}
+
+export class MigrationLockError extends Error {
+  readonly timeoutSeconds: number;
+
+  constructor(timeoutSeconds: number) {
+    super(
+      `could not acquire the migration lock within ${timeoutSeconds}s — another migrate up is probably still running`,
+    );
+    this.name = "MigrationLockError";
+    this.timeoutSeconds = timeoutSeconds;
+  }
+}
+
 export class GitStageError extends Error {
   readonly file: string;
   readonly exitCode: number;

package/src/api/run-step.ts

@@ -0,0 +1,13 @@
+import { type SQL } from "bun";
+import type { MigrationDriver } from "../core/driver.js";
+
+export async function runMigrationStep(
+  driver: MigrationDriver,
+  step: (tx?: SQL) => Promise<void>,
+): Promise<void> {
+  if (step.length > 0) {
+    await driver.transaction((tx) => step(tx));
+    return;
+  }
+  await step();
+}

package/src/api/status.ts

@@ -0,0 +1,20 @@
+import { listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
+import type { MigrateOptions, MigrateStatusResult } from "./options.js";
+import { runWithDriver } from "./run-with-driver.js";
+
+export async function migrateStatus(options: MigrateOptions = {}): Promise<MigrateStatusResult> {
+  const listDir = resolveListDir(options.listDir);
+
+  return runWithDriver(options, async (driver) => {
+    await driver.install();
+
+    const files = await listFiles(listDir, MIGRATION_EXTENSIONS);
+    const executed = await driver.listExecuted();
+    const appliedNames = new Set(executed.map((entry) => entry.name));
+
+    return {
+      applied: executed,
+      pending: files.filter((file) => !appliedNames.has(file)),
+    };
+  });
+}