bunsql-native-migrate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tekina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# bunsql-native-migrate
+
+[![CI](https://github.com/TekinaLiadon/bunsql-migrate/actions/workflows/ci.yml/badge.svg)](https://github.com/TekinaLiadon/bunsql-migrate/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/bunsql-native-migrate.svg)](https://www.npmjs.com/package/bunsql-native-migrate)
+
+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.
+
+## 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 dependencies**.
+- **Checksums** — every applied migration is checksummed (SHA-256). A modified applied file fails the run instead of silently drifting.
+- **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.
+
+## Installation
+
+```bash
+bun add bunsql-native-migrate
+```
+
+Requires Bun ≥ 1.4.2 — the version this package is developed and tested against. (The unified `Bun.SQL` client it is built on exists since Bun 1.2.21, when MySQL/MariaDB and SQLite support were added.)
+
+## Quick start
+
+```bash
+# create migrations/<timestamp>_<name>.js from the stub template
+bunx bunsql-native-migrate create add_users_table
+
+# create the tracking table (optional — up() does it automatically)
+bunx bunsql-native-migrate install
+
+# apply pending migrations
+bunx bunsql-native-migrate up
+
+# roll back the last applied migration
+bunx bunsql-native-migrate down
+```
+
+The CLI reads `DATABASE_URL` from the environment (or a `.env` file — Bun loads it automatically).
+
+### Migration file format
+
+```js
+import { sql } from "bun";
+
+const up = async () => {
+  await sql`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)`;
+};
+
+const down = async () => {
+  await sql`DROP TABLE users`;
+};
+
+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:
+
+```
+9999999999999_2026_09_13_add_users_table.js
+```
+
+### 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.
+
+Absolute paths are passed through unchanged, which is the safe choice for CI/CD and other automation where the working directory is not guaranteed to be the repository root:
+
+```bash
+DATABASE_URL=$SECRET_URL bunx bunsql-native-migrate up --dir "$CI_WORKSPACE/migrations"
+```
+
+This resolution is part of the library contract: `resolveListDir` (and therefore every API function) always returns a fully qualified absolute path, so programmatic callers can pass either form and get identical behavior from any working directory.
+
+## CLI reference
+
+```
+bunsql-native-migrate <up|down|install|create [name]> [--dir <migrations-dir>] [--git] [--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.                                                                         |
+
+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.
+
+## Programmatic API
+
+```ts
+import {
+  migrateUp,
+  migrateDown,
+  installMigrations,
+  createMigration,
+  createDriver,
+  ChecksumDriftError,
+  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
+});
+
+const { reverted } = await migrateDown(); // reverted: string | null
+
+await installMigrations(); // creates the tracking table
+
+const filename = await createMigration({ name: "add_users_table", listDir: "./migrations" });
+```
+
+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                                                                   |
+
+### Drivers
+
+The driver is picked from the URL protocol:
+
+| Protocol                       | Client                    | Notes                                                                                                                       |
+| ------------------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `postgres://`, `postgresql://` | `Bun.SQL` (PostgreSQL)    | Full-featured backend of `Bun.SQL`.                                                                                         |
+| `mariadb://`, `mysql://`       | `Bun.SQL` (MySQL/MariaDB) | MySQL 8's `caching_sha2_password` over plain TCP requires TLS or `allowPublicKeyRetrieval: true` on the server config side. |
+| `sqlite://`, `sqlite:`         | `Bun.SQL` (SQLite)        | Single connection, no pooling — fine for migrations.                                                                        |
+
+All three adapters share the same `Bun.SQL` tagged-template API, so migration files (`import { sql } from "bun"`) work identically regardless of the database.
+
+Known MySQL/MariaDB limitation of `Bun.SQL` (not used by this package, good to know for your own migrations): no `RETURNING` clause; use `result.lastInsertRowid` or a follow-up `SELECT` instead.
+
+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`).
+
+### Tracking table
+
+Applied migrations are recorded in a `migrations` table with a unique name and a SHA-256 checksum. The table lives in the database you connect to: two projects pointed at the same database share one history and one `down` stack — give each project its own database. `migrate:up` aborts when an applied file has been modified after the fact:
+
+```
+1_first.js was modified after it was applied — restore the file or resolve the drift manually
+```
+
+Records created before checksums existed (checksum `NULL`) are backfilled on the next `up`.
+
+### 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.
+
+`createMigration` with `git: true` throws `GitStageError` when `git add` fails (no repository, ignored path, …) — the migration file itself is still created on disk.
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "bunsql-native-migrate",
+  "version": "0.1.0",
+  "description": "Zero-ORM SQL file migrations for Bun: PostgreSQL, MySQL/MariaDB and SQLite through the built-in Bun.SQL client",
+  "keywords": [
+    "bun",
+    "cli",
+    "mariadb",
+    "migrations",
+    "mysql",
+    "postgres",
+    "sql",
+    "sqlite"
+  ],
+  "homepage": "https://github.com/TekinaLiadon/bunsql-migrate#readme",
+  "bugs": "https://github.com/TekinaLiadon/bunsql-migrate/issues",
+  "license": "MIT",
+  "author": "Tekina",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TekinaLiadon/bunsql-migrate.git"
+  },
+  "bin": {
+    "bunsql-native-migrate": "src/cli/main.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "@typescript/native-preview": "^7.0.0-dev.20260707.2",
+    "bun-types": "1.4.2",
+    "oxfmt": "^0.46.0",
+    "oxlint": "^1.80.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
+  }
+}

package/src/api/create.ts

@@ -0,0 +1,95 @@
+import path from "node:path";
+import { mkdir, open, type FileHandle } from "node:fs/promises";
+import { randomName } from "../core/random-name.js";
+import { resolveListDir } from "../core/fs.js";
+import { log } from "../core/console.js";
+import { GitStageError } from "./options.js";
+
+export interface CreateOptions {
+  name?: string;
+  git?: boolean;
+  listDir: string;
+}
+
+const STUB_TEMPLATE = `import { sql } from "bun";
+// Write your migration SQL here
+const up = async () => {};
+
+// Write your rollback SQL here
+const down = async () => {};
+
+export { up, down };
+`;
+
+async function stageInGit(filePath: string): Promise<void> {
+  const add = Bun.spawn({
+    cmd: ["git", "add", filePath],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const stderr = await new Response(add.stderr).text();
+  const exitCode = await add.exited;
+  if (exitCode !== 0) {
+    throw new GitStageError(filePath, exitCode, stderr.trim());
+  }
+}
+
+function migrationFilename(name: string, date: Date): string {
+  const pad = (value: number) => (value <= 9 ? `0${value}` : `${value}`);
+  const MAX_TIME = 9999999999999;
+  const invertedTime = (MAX_TIME - date.getTime()).toString().padStart(13, "0");
+  const timestamp = [
+    invertedTime,
+    date.getUTCFullYear(),
+    pad(date.getUTCMonth() + 1),
+    pad(date.getUTCDate()),
+  ].join("_");
+  return `${timestamp}_${name}.js`;
+}
+
+async function writeStubExclusively(filePath: string): Promise<boolean> {
+  let handle: FileHandle;
+  try {
+    handle = await open(filePath, "wx");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(STUB_TEMPLATE);
+  } finally {
+    await handle.close();
+  }
+  return true;
+}
+
+export async function createMigration(options: CreateOptions): Promise<string> {
+  const name = options.name ?? randomName();
+  await mkdir(options.listDir, { recursive: true });
+  let filename = migrationFilename(name, new Date());
+  let filePath = path.join(options.listDir, filename);
+  while (!(await writeStubExclusively(filePath))) {
+    await Bun.sleep(1);
+    filename = migrationFilename(name, new Date());
+    filePath = path.join(options.listDir, filename);
+  }
+
+  if (options.git) {
+    await stageInGit(filePath);
+  }
+
+  return filename;
+}
+
+export async function createMigrationCommand(
+  options: Omit<CreateOptions, "listDir"> & { listDir?: string },
+): Promise<string> {
+  const filename = await createMigration({ ...options, listDir: resolveListDir(options.listDir) });
+  log({ text: `Migration created: ${filename}`, type: "success" });
+  if (options.git) {
+    log({ text: `Staged in git: ${filename}`, type: "success" });
+  }
+  return filename;
+}

package/src/api/down.ts

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { getDatabaseUrl } from "../core/env.js";
+import { createDriver } from "../core/driver.js";
+import { resolveListDir } from "../core/fs.js";
+import { log } from "../core/console.js";
+import type { MigrateDownResult, MigrateOptions } from "./options.js";
+
+export async function migrateDown(options: MigrateOptions = {}): Promise<MigrateDownResult> {
+  const url = getDatabaseUrl(options.databaseUrl);
+  const listDir = resolveListDir(options.listDir);
+  const driver = await createDriver(url);
+
+  try {
+    const executed = await driver.listExecuted();
+    if (executed.length === 0) {
+      log({ text: "No migrations to rollback.", type: "warn" });
+      return { reverted: null };
+    }
+
+    const file = executed[executed.length - 1]!.name;
+    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 { reverted: file };
+    }
+
+    await mod.down();
+    await driver.remove(file);
+    log({ text: `${file} rolled back`, type: "success" });
+    return { reverted: file };
+  } finally {
+    await driver.close();
+  }
+}

package/src/api/install.ts

@@ -0,0 +1,15 @@
+import { getDatabaseUrl } from "../core/env.js";
+import { createDriver } from "../core/driver.js";
+import { log } from "../core/console.js";
+import type { MigrateOptions } from "./options.js";
+
+export async function installMigrations(options: MigrateOptions = {}): Promise<void> {
+  const url = getDatabaseUrl(options.databaseUrl);
+  const driver = await createDriver(url);
+  try {
+    await driver.install();
+    log({ text: "Migration table created!", type: "success" });
+  } finally {
+    await driver.close();
+  }
+}

package/src/api/options.ts

@@ -0,0 +1,39 @@
+export interface MigrateOptions {
+  databaseUrl?: string;
+  listDir?: string;
+}
+
+export interface MigrateUpResult {
+  applied: string[];
+}
+
+export interface MigrateDownResult {
+  reverted: string | null;
+}
+
+export class ChecksumDriftError extends Error {
+  readonly file: string;
+
+  constructor(file: string) {
+    super(
+      `${file} was modified after it was applied — restore the file or resolve the drift manually`,
+    );
+    this.name = "ChecksumDriftError";
+    this.file = file;
+  }
+}
+
+export class GitStageError extends Error {
+  readonly file: string;
+  readonly exitCode: number;
+
+  constructor(file: string, exitCode: number, reason: string) {
+    super(
+      `git add failed for ${file} (exit code ${exitCode})` +
+        `${reason ? `: ${reason}` : ""} — the file was created but is not staged`,
+    );
+    this.name = "GitStageError";
+    this.file = file;
+    this.exitCode = exitCode;
+  }
+}

package/src/api/up.ts

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { getDatabaseUrl } from "../core/env.js";
+import { createDriver } from "../core/driver.js";
+import { checksumFile, listFiles, resolveListDir } from "../core/fs.js";
+import { log } from "../core/console.js";
+import { type MigrateOptions, type MigrateUpResult, ChecksumDriftError } from "./options.js";
+
+export async function migrateUp(options: MigrateOptions = {}): Promise<MigrateUpResult> {
+  const url = getDatabaseUrl(options.databaseUrl);
+  const listDir = resolveListDir(options.listDir);
+  const driver = await createDriver(url);
+
+  try {
+    await driver.install();
+
+    const allFiles = await listFiles(listDir, "js");
+    const checksums = new Map<string, string>();
+    for (const file of allFiles) {
+      checksums.set(file, await checksumFile(path.join(listDir, file)));
+    }
+
+    const executed = await driver.listExecuted();
+    const executedByName = new Map(executed.map((entry) => [entry.name, entry]));
+
+    for (const file of allFiles) {
+      const record = executedByName.get(file);
+      if (!record) continue;
+
+      const checksum = checksums.get(file);
+      if (!checksum) 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);
+      }
+    }
+
+    const pending = allFiles.filter((file) => !executedByName.has(file));
+    const applied: string[] = [];
+
+    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;
+        }
+        await 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 };
+  } finally {
+    await driver.close();
+  }
+}

package/src/cli/main.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env bun
+import { migrateUp } from "../api/up.js";
+import { migrateDown } from "../api/down.js";
+import { installMigrations } from "../api/install.js";
+import { createMigrationCommand } from "../api/create.js";
+import { ChecksumDriftError } from "../api/options.js";
+import { log } from "../core/console.js";
+
+interface CliArgs {
+  command: string | undefined;
+  positional: string[];
+  dir?: string | undefined;
+  git: boolean;
+  help: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const positional: string[] = [];
+  let dir: string | undefined;
+  let git = false;
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--dir") {
+      dir = argv[++i];
+    } else if (arg === "--git") {
+      git = true;
+    } else if (arg === "--help" || arg === "-h") {
+      help = true;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { command: positional.shift(), positional, dir, git, help };
+}
+
+function usage(exitCode: number): never {
+  log({
+    text: "Usage: bunsql-native-migrate <up|down|install|create [name]> [--dir <migrations-dir>] [--git] [--help]",
+    type: "info",
+  });
+  process.exit(exitCode);
+}
+
+const args = parseArgs(process.argv.slice(2));
+const listDirOptions = args.dir ? { listDir: args.dir } : {};
+
+if (args.help) {
+  usage(0);
+}
+
+try {
+  switch (args.command) {
+    case "up": {
+      const { applied } = await migrateUp(listDirOptions);
+      if (applied.length > 0) {
+        log({ text: `Applied ${applied.length} migration(s).`, type: "success" });
+      }
+      break;
+    }
+    case "down": {
+      await migrateDown(listDirOptions);
+      break;
+    }
+    case "install": {
+      await installMigrations(listDirOptions);
+      break;
+    }
+    case "create": {
+      const [name] = args.positional;
+      await createMigrationCommand({
+        ...(name ? { name } : {}),
+        git: args.git,
+        ...listDirOptions,
+      });
+      break;
+    }
+    default:
+      usage(1);
+  }
+} catch (error) {
+  if (error instanceof ChecksumDriftError) {
+    log({ text: error.message, type: "error" });
+  } else {
+    log({ text: "Migration command failed", type: "error", error });
+  }
+  process.exit(1);
+}

package/src/core/console.ts

@@ -0,0 +1,47 @@
+const colors = {
+  success: "\x1b[32m%s\x1b[0m",
+  warn: "\x1b[33m%s\x1b[0m",
+  error: "\x1b[31m%s\x1b[0m",
+  info: "",
+} as const;
+
+type LogLevel = keyof typeof colors;
+
+interface LogOptions {
+  text: string;
+  type: LogLevel;
+  error?: unknown;
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function formatError(error: any): void {
+  if (error instanceof Error) {
+    console.log(error.message);
+    if (error.stack) console.log(error.stack);
+    return;
+  }
+  if (typeof error === "object" && error !== null) {
+    if ("code" in error && "detail" in error) {
+      console.table(error);
+      return;
+    }
+    if ("code" in error && "errno" in error) {
+      console.log(error.code);
+      console.log(error.errno);
+      if ("byteOffset" in error) console.log(error.byteOffset);
+      return;
+    }
+    if ("message" in error) {
+      console.log(error.message);
+      return;
+    }
+  }
+  console.log(String(error));
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+export function log({ text, type, error = null }: LogOptions): void {
+  console.log(colors[type], text);
+  if (!error) return;
+  formatError(error);
+}

package/src/core/driver.ts

@@ -0,0 +1,46 @@
+export interface ExecutedMigration {
+  name: string;
+  checksum: string | null;
+}
+
+export interface MigrationDriver {
+  install(): Promise<void>;
+  listExecuted(): Promise<ExecutedMigration[]>;
+  record(migration: string, checksum: string): Promise<void>;
+  setChecksum(migration: string, checksum: string): Promise<void>;
+  remove(migration: string): Promise<void>;
+  close(): Promise<void>;
+}
+
+export async function createDriver(databaseUrl: string): Promise<MigrationDriver> {
+  let protocol: string;
+  try {
+    protocol = new URL(databaseUrl).protocol.replace(":", "");
+  } catch {
+    if (databaseUrl.startsWith("sqlite:")) {
+      protocol = "sqlite";
+    } else {
+      throw new Error(`Cannot parse database URL: ${databaseUrl}`);
+    }
+  }
+  switch (protocol) {
+    case "postgres":
+    case "postgresql": {
+      const mod = await import("./../drivers/postgres.js");
+      return mod.create(databaseUrl);
+    }
+    case "sqlite": {
+      const mod = await import("./../drivers/sqlite.js");
+      return mod.create(databaseUrl);
+    }
+    case "mariadb":
+    case "mysql": {
+      const mod = await import("./../drivers/mariadb.js");
+      return mod.create(databaseUrl);
+    }
+    default:
+      throw new Error(
+        `Unsupported database URL protocol: ${protocol}. Supported: postgres, mariadb/mysql, sqlite.`,
+      );
+  }
+}

package/src/core/env.ts

@@ -0,0 +1,7 @@
+export function getDatabaseUrl(override?: string): string {
+  const url = override ?? process.env["DATABASE_URL"];
+  if (!url) {
+    throw new Error("DATABASE_URL is not set. Add it to .env or export it in your shell.");
+  }
+  return url;
+}

package/src/core/fs.ts

@@ -0,0 +1,29 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+
+export const DEFAULT_MIGRATIONS_DIR = "migrations";
+
+export async function listFiles(dir: string, ext: 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}`)) {
+      matchedFiles.push(entry.name);
+    }
+  }
+  return matchedFiles.sort().reverse();
+}
+
+export async function checksumFile(filePath: string): Promise<string> {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(await Bun.file(filePath).arrayBuffer());
+  return hasher.digest("hex");
+}
+
+export function resolveListDir(override?: string): string {
+  return path.resolve(
+    override ??
+      process.env["MIGRATION_LIST_DIR"] ??
+      path.join(process.cwd(), DEFAULT_MIGRATIONS_DIR),
+  );
+}

package/src/core/random-name.ts

@@ -0,0 +1,111 @@
+const adjectives = [
+  "brave",
+  "calm",
+  "dusty",
+  "eager",
+  "fair",
+  "golden",
+  "hasty",
+  "jolly",
+  "keen",
+  "lucky",
+  "merry",
+  "noble",
+  "proud",
+  "quick",
+  "sharp",
+  "swift",
+  "tall",
+  "vivid",
+  "warm",
+  "young",
+  "bold",
+  "crisp",
+  "dry",
+  "fine",
+  "glad",
+  "kind",
+  "light",
+  "mild",
+  "neat",
+  "prime",
+  "rare",
+  "safe",
+  "true",
+  "vast",
+  "wise",
+  "apt",
+  "bright",
+  "deep",
+  "free",
+  "grand",
+  "honest",
+  "just",
+  "lean",
+  "open",
+  "plain",
+  "still",
+  "wild",
+  "cool",
+  "soft",
+  "dark",
+];
+
+const nouns = [
+  "comet",
+  "river",
+  "stone",
+  "falcon",
+  "oak",
+  "summit",
+  "breeze",
+  "creek",
+  "ember",
+  "glacier",
+  "harbor",
+  "island",
+  "jasper",
+  "kettle",
+  "lantern",
+  "meadow",
+  "nectar",
+  "orchid",
+  "prism",
+  "quartz",
+  "ridge",
+  "tide",
+  "valley",
+  "willow",
+  "zephyr",
+  "bolt",
+  "cliff",
+  "dawn",
+  "fern",
+  "grove",
+  "haze",
+  "iris",
+  "jet",
+  "kite",
+  "lark",
+  "marsh",
+  "nest",
+  "opal",
+  "peak",
+  "reed",
+  "sage",
+  "thorn",
+  "vine",
+  "wolf",
+  "ash",
+  "bay",
+  "cape",
+  "dune",
+  "flint",
+  "gleam",
+];
+
+export function randomName(): string {
+  const adj = adjectives[Math.floor(Math.random() * adjectives.length)]!;
+  const noun = nouns[Math.floor(Math.random() * nouns.length)]!;
+  return `${adj}_${noun}`;
+}

package/src/drivers/mariadb.ts

@@ -0,0 +1,45 @@
+import { SQL } from "bun";
+import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
+
+export function create(databaseUrl: string): MigrationDriver {
+  const db = new SQL(databaseUrl);
+
+  return {
+    async install() {
+      await db`CREATE TABLE IF NOT EXISTS migrations (
+        id INTEGER PRIMARY KEY AUTO_INCREMENT,
+        migration VARCHAR(255) NOT NULL,
+        checksum VARCHAR(64)
+      )`;
+      await db`ALTER TABLE migrations ADD COLUMN IF NOT EXISTS checksum VARCHAR(64)`;
+      await db`CREATE UNIQUE INDEX IF NOT EXISTS migrations_migration_unique ON migrations (migration)`;
+    },
+
+    async listExecuted() {
+      const rows = await db`SELECT migration, checksum FROM migrations ORDER BY id ASC`;
+      return rows.map(
+        (r: { migration: string; checksum: string | null }): ExecutedMigration => ({
+          name: r.migration,
+          checksum: r.checksum ?? null,
+        }),
+      );
+    },
+
+    async record(migration: string, checksum: string) {
+      await db`INSERT IGNORE INTO migrations (migration, checksum)
+        VALUES (${migration}, ${checksum})`;
+    },
+
+    async setChecksum(migration: string, checksum: string) {
+      await db`UPDATE migrations SET checksum = ${checksum} WHERE migration = ${migration}`;
+    },
+
+    async remove(migration: string) {
+      await db`DELETE FROM migrations WHERE migration = ${migration}`;
+    },
+
+    async close() {
+      db.close({ timeout: 0 });
+    },
+  };
+}

package/src/drivers/postgres.ts

@@ -0,0 +1,46 @@
+import { SQL } from "bun";
+import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
+
+export function create(databaseUrl: string): MigrationDriver {
+  const db = new SQL(databaseUrl);
+
+  return {
+    async install() {
+      await db`CREATE TABLE IF NOT EXISTS migrations (
+        id SERIAL PRIMARY KEY,
+        migration VARCHAR(255) NOT NULL,
+        checksum VARCHAR(64)
+      )`;
+      await db`ALTER TABLE migrations ADD COLUMN IF NOT EXISTS checksum VARCHAR(64)`;
+      await db`CREATE UNIQUE INDEX IF NOT EXISTS migrations_migration_unique ON migrations (migration)`;
+    },
+
+    async listExecuted() {
+      const rows = await db`SELECT migration, checksum FROM migrations ORDER BY id ASC`;
+      return rows.map(
+        (r: { migration: string; checksum: string | null }): ExecutedMigration => ({
+          name: r.migration,
+          checksum: r.checksum ?? null,
+        }),
+      );
+    },
+
+    async record(migration: string, checksum: string) {
+      await db`INSERT INTO migrations (migration, checksum)
+        VALUES (${migration}, ${checksum})
+        ON CONFLICT (migration) DO NOTHING`;
+    },
+
+    async setChecksum(migration: string, checksum: string) {
+      await db`UPDATE migrations SET checksum = ${checksum} WHERE migration = ${migration}`;
+    },
+
+    async remove(migration: string) {
+      await db`DELETE FROM migrations WHERE migration = ${migration}`;
+    },
+
+    async close() {
+      db.close({ timeout: 0 });
+    },
+  };
+}

package/src/drivers/sqlite.ts

@@ -0,0 +1,51 @@
+import { SQL } from "bun";
+import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
+
+export function create(databaseUrl: string): MigrationDriver {
+  const db = new SQL(databaseUrl);
+
+  return {
+    async install() {
+      await db`CREATE TABLE IF NOT EXISTS migrations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        migration TEXT NOT NULL,
+        checksum TEXT
+      )`;
+      const columns = (await db`PRAGMA table_info(migrations)`) as Array<{
+        name: string;
+      }>;
+      const hasChecksum = columns.some((column) => column.name === "checksum");
+      if (!hasChecksum) {
+        await db`ALTER TABLE migrations ADD COLUMN checksum TEXT`;
+      }
+      await db`CREATE UNIQUE INDEX IF NOT EXISTS migrations_migration_unique ON migrations (migration)`;
+    },
+
+    async listExecuted() {
+      const rows = await db`SELECT migration, checksum FROM migrations ORDER BY id ASC`;
+      return rows.map(
+        (r: { migration: string; checksum: string | null }): ExecutedMigration => ({
+          name: r.migration,
+          checksum: r.checksum ?? null,
+        }),
+      );
+    },
+
+    async record(migration: string, checksum: string) {
+      await db`INSERT OR IGNORE INTO migrations (migration, checksum)
+        VALUES (${migration}, ${checksum})`;
+    },
+
+    async setChecksum(migration: string, checksum: string) {
+      await db`UPDATE migrations SET checksum = ${checksum} WHERE migration = ${migration}`;
+    },
+
+    async remove(migration: string) {
+      await db`DELETE FROM migrations WHERE migration = ${migration}`;
+    },
+
+    async close() {
+      db.close({ timeout: 0 });
+    },
+  };
+}

package/src/index.ts

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