bunsql-native-migrate 0.1.2 → 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 (optionally `up(tx)`/`down(tx)` for transactional migrations, see below) 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,10 +65,10 @@ 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
@@ -81,7 +88,7 @@ const down = async (tx) => {
 export { up, down };
 ```
 
-- `bunsql-native-migrate create` generates stubs in this form by default; `tx` is a Bun `SQL` client bound to the same database the runner is connected to.
+- `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).
@@ -101,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.
 
@@ -125,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
 
@@ -146,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
 
@@ -169,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
 
@@ -181,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.2",
+  "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,13 +5,16 @@ 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";
+const JS_TEMPLATE = `import { sql } from "bun";
 // Write your migration SQL here (tx runs inside a transaction)
 const up = async (tx) => {};
 
@@ -21,6 +24,20 @@ 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,33 +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 runMigrationStep(driver, 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/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)),
+    };
+  });
+}

package/src/api/up.ts

@@ -1,68 +1,92 @@
 import path from "node:path";
-import { checksumFile, listFiles, resolveListDir } from "../core/fs.js";
+import { checksumFile, listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
 import { log } from "../core/console.js";
-import { type MigrateOptions, type MigrateUpResult, ChecksumDriftError } from "./options.js";
+import {
+  type MigrateUpOptions,
+  type MigrateUpResult,
+  ChecksumDriftError,
+  MigrationNotFoundError,
+} from "./options.js";
 import { runWithDriver } from "./run-with-driver.js";
 import { runMigrationStep } from "./run-step.js";
+import { resolveLockTimeout, withMigrationLock } from "./lock.js";
 
-export async function migrateUp(options: MigrateOptions = {}): Promise<MigrateUpResult> {
+export async function migrateUp(options: MigrateUpOptions = {}): Promise<MigrateUpResult> {
   const listDir = resolveListDir(options.listDir);
+  const target = options.to;
+  const lockTimeout = resolveLockTimeout(options.lockTimeout);
 
   return runWithDriver(options, async (driver) => {
     await driver.install();
 
-    const allFiles = await listFiles(listDir, "js");
-    const checksums = new Map(
-      await Promise.all(
-        allFiles.map(async (file) => [file, await checksumFile(path.join(listDir, file))] as const),
-      ),
-    );
+    return withMigrationLock(driver, lockTimeout, async () => {
+      const allFiles = await listFiles(listDir, MIGRATION_EXTENSIONS);
+      if (target !== undefined && !allFiles.includes(target)) {
+        throw new MigrationNotFoundError(target);
+      }
+
+      const checksums = new Map(
+        await Promise.all(
+          allFiles.map(
+            async (file) => [file, await checksumFile(path.join(listDir, file))] as const,
+          ),
+        ),
+      );
+
+      const executed = await driver.listExecuted();
+      const executedByName = new Map(executed.map((entry) => [entry.name, entry]));
 
-    const executed = await driver.listExecuted();
-    const executedByName = new Map(executed.map((entry) => [entry.name, entry]));
+      for (const [file, checksum] of checksums) {
+        const record = executedByName.get(file);
+        if (!record) continue;
 
-    for (const [file, checksum] of checksums) {
-      const record = executedByName.get(file);
-      if (!record) continue;
+        if (record.checksum === null) {
+          await driver.setChecksum(file, checksum);
+          log({ text: `${file} checksum saved (legacy record)`, type: "info" });
+          continue;
+        }
 
-      if (record.checksum === null) {
-        await driver.setChecksum(file, checksum);
-        log({ text: `${file} checksum saved (legacy record)`, type: "info" });
-        continue;
+        if (record.checksum !== checksum) {
+          throw new ChecksumDriftError(file);
+        }
       }
 
-      if (record.checksum !== checksum) {
-        throw new ChecksumDriftError(file);
+      let pending = allFiles.filter((file) => !executedByName.has(file));
+      if (target !== undefined) {
+        if (executedByName.has(target)) {
+          log({ text: `${target} is already applied.`, type: "info" });
+          return { applied: [] };
+        }
+        pending = pending.slice(0, pending.indexOf(target) + 1);
       }
-    }
 
-    const pending = allFiles.filter((file) => !executedByName.has(file));
-    const applied: string[] = [];
+      const applied: string[] = [];
 
-    if (pending.length === 0) {
-      log({ text: "No pending migrations.", type: "warn" });
-      return { applied };
-    }
+      if (pending.length === 0) {
+        log({ text: "No pending migrations.", type: "warn" });
+        return { applied };
+      }
 
-    for (const file of pending) {
-      const checksum = checksums.get(file);
-      if (!checksum) continue;
-      try {
-        const mod = await import(path.join(listDir, file));
-        if (typeof mod.up !== "function") {
-          log({ text: `${file} has no up() export, skipping`, type: "warn" });
-          continue;
+      for (const file of pending) {
+        const checksum = checksums.get(file);
+        if (!checksum) continue;
+        try {
+          const mod = await import(path.join(listDir, file));
+          if (typeof mod.up !== "function") {
+            log({ text: `${file} has no up() export, skipping`, type: "warn" });
+            continue;
+          }
+          await runMigrationStep(driver, mod.up);
+          await driver.record(file, checksum);
+          applied.push(file);
+          log({ text: `${file} migrated up`, type: "success" });
+        } catch (error) {
+          log({ text: `${file} migration failed`, type: "error", error });
+          throw error;
         }
-        await runMigrationStep(driver, mod.up);
-        await driver.record(file, checksum);
-        applied.push(file);
-        log({ text: `${file} migrated up`, type: "success" });
-      } catch (error) {
-        log({ text: `${file} migration failed`, type: "error", error });
-        throw error;
       }
-    }
 
-    return { applied };
+      return { applied };
+    });
   });
 }

package/src/cli/main.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env bun
 import { migrateUp } from "../api/up.js";
 import { migrateDown } from "../api/down.js";
+import { migrateStatus } from "../api/status.js";
 import { installMigrations } from "../api/install.js";
-import { createMigrationCommand } from "../api/create.js";
-import { ChecksumDriftError } from "../api/options.js";
+import { createMigrationCommand, type MigrationLang } from "../api/create.js";
+import { ChecksumDriftError, MigrationLockError, MigrationNotFoundError } from "../api/options.js";
 import { log } from "../core/console.js";
 
 interface CliArgs {
@@ -11,6 +12,11 @@ interface CliArgs {
   positional: string[];
   dir?: string | undefined;
   git: boolean;
+  lang?: MigrationLang | undefined;
+  to?: string | undefined;
+  lockTimeout?: number | undefined;
+  all: boolean;
+  strict: boolean;
   help: boolean;
 }
 
@@ -18,6 +24,11 @@ function parseArgs(argv: string[]): CliArgs {
   const positional: string[] = [];
   let dir: string | undefined;
   let git = false;
+  let lang: MigrationLang | undefined;
+  let to: string | undefined;
+  let lockTimeout: number | undefined;
+  let all = false;
+  let strict = false;
   let help = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]!;
@@ -25,18 +36,60 @@ function parseArgs(argv: string[]): CliArgs {
       dir = argv[++i];
     } else if (arg === "--git") {
       git = true;
+    } else if (arg === "--lang") {
+      const value = argv[++i];
+      if (value !== "js" && value !== "ts") {
+        log({
+          text: `Unknown --lang value: ${value ?? "(missing)"} (expected js or ts)`,
+          type: "error",
+        });
+        usage(1);
+      }
+      lang = value;
+    } else if (arg === "--to") {
+      to = argv[++i];
+      if (to === undefined) {
+        log({ text: "--to requires a migration file name", type: "error" });
+        usage(1);
+      }
+    } else if (arg === "--lock-timeout") {
+      const value = argv[++i];
+      const parsed = Number(value);
+      if (value === undefined || !Number.isInteger(parsed) || parsed < 0) {
+        log({
+          text: `Invalid --lock-timeout: ${value ?? "(missing)"} (expected a non-negative integer of seconds)`,
+          type: "error",
+        });
+        usage(1);
+      }
+      lockTimeout = parsed;
+    } else if (arg === "--all") {
+      all = true;
+    } else if (arg === "--strict") {
+      strict = true;
     } else if (arg === "--help" || arg === "-h") {
       help = true;
     } else {
       positional.push(arg);
     }
   }
-  return { command: positional.shift(), positional, dir, git, help };
+  return {
+    command: positional.shift(),
+    positional,
+    dir,
+    git,
+    lang,
+    to,
+    lockTimeout,
+    all,
+    strict,
+    help,
+  };
 }
 
 function usage(exitCode: number): never {
   log({
-    text: "Usage: bunsql-native-migrate <up|down|install|create [name]> [--dir <migrations-dir>] [--git] [--help]",
+    text: "Usage: 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]",
     type: "info",
   });
   process.exit(exitCode);
@@ -52,14 +105,40 @@ if (args.help) {
 try {
   switch (args.command) {
     case "up": {
-      const { applied } = await migrateUp(listDirOptions);
+      const { applied } = await migrateUp({
+        ...listDirOptions,
+        ...(args.to ? { to: args.to } : {}),
+        ...(args.lockTimeout !== undefined ? { lockTimeout: args.lockTimeout } : {}),
+      });
       if (applied.length > 0) {
         log({ text: `Applied ${applied.length} migration(s).`, type: "success" });
       }
       break;
     }
     case "down": {
-      await migrateDown(listDirOptions);
+      const [stepsArg] = args.positional;
+      if (args.all && stepsArg !== undefined) {
+        log({ text: "Use either --all or a number of steps, not both.", type: "error" });
+        usage(1);
+      }
+      let steps: number | "all" = 1;
+      if (args.all) {
+        steps = "all";
+      } else if (stepsArg !== undefined) {
+        const parsed = Number(stepsArg);
+        if (!Number.isInteger(parsed) || parsed < 1) {
+          log({
+            text: `Invalid step count: ${stepsArg} (expected a positive integer)`,
+            type: "error",
+          });
+          usage(1);
+        }
+        steps = parsed;
+      }
+      const { reverted } = await migrateDown({ ...listDirOptions, steps });
+      if (reverted.length > 0) {
+        log({ text: `Reverted ${reverted.length} migration(s).`, type: "success" });
+      }
       break;
     }
     case "install": {
@@ -70,16 +149,36 @@ try {
       const [name] = args.positional;
       await createMigrationCommand({
         ...(name ? { name } : {}),
+        ...(args.lang ? { lang: args.lang } : {}),
         git: args.git,
         ...listDirOptions,
       });
       break;
     }
+    case "status": {
+      const { applied, pending } = await migrateStatus(listDirOptions);
+      for (const entry of applied) {
+        log({ text: `${entry.name} applied`, type: "info" });
+      }
+      for (const file of pending) {
+        log({ text: `${file} pending`, type: "warn" });
+      }
+      log({ text: `${applied.length} applied, ${pending.length} pending`, type: "info" });
+      if (args.strict && pending.length > 0) {
+        log({ text: `Strict mode: ${pending.length} pending migration(s).`, type: "warn" });
+        process.exit(1);
+      }
+      break;
+    }
     default:
       usage(1);
   }
 } catch (error) {
-  if (error instanceof ChecksumDriftError) {
+  if (
+    error instanceof ChecksumDriftError ||
+    error instanceof MigrationNotFoundError ||
+    error instanceof MigrationLockError
+  ) {
     log({ text: error.message, type: "error" });
   } else {
     log({ text: "Migration command failed", type: "error", error });

package/src/core/driver.ts

@@ -12,6 +12,8 @@ export interface MigrationDriver {
   setChecksum(migration: string, checksum: string): Promise<void>;
   remove(migration: string): Promise<void>;
   transaction<T>(run: (tx: SQL) => Promise<T>): Promise<T>;
+  tryLock?(timeoutSeconds: number): Promise<boolean>;
+  releaseLock?(): Promise<void>;
   close(): Promise<void>;
 }
 

package/src/core/fs.ts

@@ -3,11 +3,13 @@ import path from "node:path";
 
 export const DEFAULT_MIGRATIONS_DIR = "migrations";
 
-export async function listFiles(dir: string, ext: string): Promise<string[]> {
+export const MIGRATION_EXTENSIONS = ["js", "ts"] as const;
+
+export async function listFiles(dir: string, extensions: readonly string[]): Promise<string[]> {
   const matchedFiles: string[] = [];
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
-    if (entry.isFile() && entry.name.endsWith(`.${ext}`)) {
+    if (entry.isFile() && extensions.some((ext) => entry.name.endsWith(`.${ext}`))) {
       matchedFiles.push(entry.name);
     }
   }

package/src/drivers/mariadb.ts

@@ -1,6 +1,8 @@
 import { type SQL } from "bun";
 import type { MigrationDriver } from "../core/driver.js";
-import { createSqlDriver } from "./shared.js";
+import { createReservedLock, createSqlDriver } from "./shared.js";
+
+const LOCK_NAME_PREFIX = "bunsql-native-migrate:";
 
 async function checksumColumnExists(db: SQL): Promise<boolean> {
   const rows = await db`SELECT column_name FROM information_schema.columns
@@ -38,5 +40,20 @@ export function create(databaseUrl: string): MigrationDriver {
       await db`INSERT IGNORE INTO migrations (migration, checksum)
         VALUES (${migration}, ${checksum})`;
     },
+    createLock: (db) =>
+      createReservedLock(
+        db,
+        async (lock) => {
+          const rows =
+            (await lock`SELECT GET_LOCK(CONCAT(${LOCK_NAME_PREFIX}, MD5(DATABASE())), 0) AS locked`) as Array<{
+              locked: number | string | null;
+            }>;
+          const locked = rows[0]?.locked;
+          return locked === 1 || locked === "1";
+        },
+        async (lock) => {
+          await lock`SELECT RELEASE_LOCK(CONCAT(${LOCK_NAME_PREFIX}, MD5(DATABASE())))`;
+        },
+      ),
   });
 }

package/src/drivers/postgres.ts

@@ -1,5 +1,14 @@
+import { type SQL } from "bun";
 import type { MigrationDriver } from "../core/driver.js";
-import { createSqlDriver } from "./shared.js";
+import { createReservedLock, createSqlDriver } from "./shared.js";
+
+const LOCK_SCOPE = "bunsql-native-migrate:up";
+
+async function advisoryKeyComponents(lock: SQL): Promise<[number, number]> {
+  const rows = (await lock`SELECT current_database() AS name`) as Array<{ name: string }>;
+  const hash = Bun.hash.wyhash(`${LOCK_SCOPE}:${rows[0]?.name ?? ""}`);
+  return [Number((hash >> 32n) & 0x7fffffffn), Number(hash & 0x7fffffffn)];
+}
 
 export function create(databaseUrl: string): MigrationDriver {
   return createSqlDriver(databaseUrl, {
@@ -17,5 +26,21 @@ export function create(databaseUrl: string): MigrationDriver {
         VALUES (${migration}, ${checksum})
         ON CONFLICT (migration) DO NOTHING`;
     },
+    createLock: (db) =>
+      createReservedLock(
+        db,
+        async (lock) => {
+          const [first, second] = await advisoryKeyComponents(lock);
+          const rows =
+            (await lock`SELECT pg_try_advisory_lock(${first}, ${second}) AS locked`) as Array<{
+              locked: boolean;
+            }>;
+          return rows[0]?.locked === true;
+        },
+        async (lock) => {
+          const [first, second] = await advisoryKeyComponents(lock);
+          await lock`SELECT pg_advisory_unlock(${first}, ${second})`;
+        },
+      ),
   });
 }

package/src/drivers/shared.ts

@@ -1,13 +1,62 @@
-import { SQL } from "bun";
+import { SQL, type ReservedSQL } from "bun";
 import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
 
+export interface SqlLock {
+  tryLock(timeoutSeconds: number): Promise<boolean>;
+  releaseLock(): Promise<void>;
+  dispose(): void;
+}
+
 export interface SqlDialect {
   install(db: SQL): Promise<void>;
   record(db: SQL, migration: string, checksum: string): Promise<void>;
+  createLock?(db: SQL): SqlLock;
+}
+
+export function createReservedLock(
+  db: SQL,
+  acquire: (lock: SQL) => Promise<boolean>,
+  release: (lock: SQL) => Promise<void>,
+): SqlLock {
+  let lockConnection: ReservedSQL | null = null;
+
+  return {
+    async tryLock() {
+      const connection = await db.reserve();
+      lockConnection = connection;
+      try {
+        const acquired = await acquire(connection);
+        if (!acquired) {
+          connection.release();
+          lockConnection = null;
+        }
+        return acquired;
+      } catch (error) {
+        connection.release();
+        lockConnection = null;
+        throw error;
+      }
+    },
+    async releaseLock() {
+      const connection = lockConnection;
+      if (!connection) return;
+      lockConnection = null;
+      try {
+        await release(connection);
+      } finally {
+        connection.release();
+      }
+    },
+    dispose() {
+      lockConnection?.release();
+      lockConnection = null;
+    },
+  };
 }
 
 export function createSqlDriver(databaseUrl: string, dialect: SqlDialect): MigrationDriver {
   const db = new SQL(databaseUrl);
+  const lock = dialect.createLock?.(db);
 
   return {
     install: () => dialect.install(db),
@@ -28,7 +77,14 @@ export function createSqlDriver(databaseUrl: string, dialect: SqlDialect): Migra
       await db`DELETE FROM migrations WHERE migration = ${migration}`;
     },
     transaction: (run) => db.begin(run),
+    ...(lock
+      ? {
+          tryLock: (timeoutSeconds: number) => lock.tryLock(timeoutSeconds),
+          releaseLock: () => lock.releaseLock(),
+        }
+      : {}),
     async close() {
+      lock?.dispose();
       db.close({ timeout: 0 });
     },
   };

package/src/drivers/sqlite.ts

@@ -22,5 +22,15 @@ export function create(databaseUrl: string): MigrationDriver {
       await db`INSERT OR IGNORE INTO migrations (migration, checksum)
         VALUES (${migration}, ${checksum})`;
     },
+    createLock: (db) => ({
+      async tryLock(timeoutSeconds: number) {
+        await db.unsafe(`PRAGMA busy_timeout = ${timeoutSeconds * 1000}`);
+        return true;
+      },
+      async releaseLock() {
+        await db.unsafe("PRAGMA busy_timeout = 0");
+      },
+      dispose() {},
+    }),
   });
 }

package/src/index.ts

@@ -1,29 +1,41 @@
 import { createDriver, type ExecutedMigration, type MigrationDriver } from "./core/driver.js";
 import { migrateUp } from "./api/up.js";
 import { migrateDown } from "./api/down.js";
+import { migrateStatus } from "./api/status.js";
 import { installMigrations } from "./api/install.js";
 import { createMigration } from "./api/create.js";
 import {
+  type MigrateDownOptions,
   type MigrateDownResult,
   type MigrateOptions,
+  type MigrateStatusResult,
+  type MigrateUpOptions,
   type MigrateUpResult,
   ChecksumDriftError,
   GitStageError,
+  MigrationLockError,
+  MigrationNotFoundError,
 } from "./api/options.js";
 
 export {
   createDriver,
   migrateUp,
   migrateDown,
+  migrateStatus,
   installMigrations,
   createMigration,
   ChecksumDriftError,
   GitStageError,
+  MigrationLockError,
+  MigrationNotFoundError,
 };
 export type {
   ExecutedMigration,
   MigrationDriver,
   MigrateOptions,
+  MigrateUpOptions,
   MigrateUpResult,
+  MigrateDownOptions,
   MigrateDownResult,
+  MigrateStatusResult,
 };