bunsql-native-migrate 0.1.0 → 0.1.2

package/README.md

@@ -5,7 +5,7 @@
 
 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` 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
 
@@ -64,6 +64,28 @@ Files live in the migrations directory (default `./migrations`, override with `-
 9999999999999_2026_09_13_add_users_table.js
 ```
 
+### 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; `tx` is 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunsql-native-migrate",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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

@@ -12,11 +12,11 @@ export interface CreateOptions {
 }
 
 const STUB_TEMPLATE = `import { sql } from "bun";
-// Write your migration SQL here
-const up = async () => {};
+// 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 };
 `;

package/src/api/down.ts

@@ -1,16 +1,14 @@
 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";
+import { runWithDriver } from "./run-with-driver.js";
+import { runMigrationStep } from "./run-step.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 {
+  return runWithDriver(options, async (driver) => {
     const executed = await driver.listExecuted();
     if (executed.length === 0) {
       log({ text: "No migrations to rollback.", type: "warn" });
@@ -27,11 +25,9 @@ export async function migrateDown(options: MigrateOptions = {}): Promise<Migrate
       return { reverted: file };
     }
 
-    await mod.down();
+    await runMigrationStep(driver, 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

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

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/run-with-driver.ts

@@ -0,0 +1,16 @@
+import { getDatabaseUrl } from "../core/env.js";
+import { createDriver, type MigrationDriver } from "../core/driver.js";
+import type { MigrateOptions } from "./options.js";
+
+export async function runWithDriver<T>(
+  options: MigrateOptions,
+  run: (driver: MigrationDriver) => Promise<T>,
+): Promise<T> {
+  const url = getDatabaseUrl(options.databaseUrl);
+  const driver = await createDriver(url);
+  try {
+    return await run(driver);
+  } finally {
+    await driver.close();
+  }
+}

package/src/api/up.ts

@@ -1,34 +1,30 @@
 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";
+import { runWithDriver } from "./run-with-driver.js";
+import { runMigrationStep } from "./run-step.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 {
+  return runWithDriver(options, async (driver) => {
     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 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]));
 
-    for (const file of allFiles) {
+    for (const [file, checksum] of checksums) {
       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" });
@@ -57,7 +53,7 @@ export async function migrateUp(options: MigrateOptions = {}): Promise<MigrateUp
           log({ text: `${file} has no up() export, skipping`, type: "warn" });
           continue;
         }
-        await mod.up();
+        await runMigrationStep(driver, mod.up);
         await driver.record(file, checksum);
         applied.push(file);
         log({ text: `${file} migrated up`, type: "success" });
@@ -68,7 +64,5 @@ export async function migrateUp(options: MigrateOptions = {}): Promise<MigrateUp
     }
 
     return { applied };
-  } finally {
-    await driver.close();
-  }
+  });
 }

package/src/core/console.ts

@@ -2,7 +2,7 @@ const colors = {
   success: "\x1b[32m%s\x1b[0m",
   warn: "\x1b[33m%s\x1b[0m",
   error: "\x1b[31m%s\x1b[0m",
-  info: "",
+  info: "%s",
 } as const;
 
 type LogLevel = keyof typeof colors;

package/src/core/driver.ts

@@ -1,3 +1,5 @@
+import { type SQL } from "bun";
+
 export interface ExecutedMigration {
   name: string;
   checksum: string | null;
@@ -9,6 +11,7 @@ export interface MigrationDriver {
   record(migration: string, checksum: string): Promise<void>;
   setChecksum(migration: string, checksum: string): Promise<void>;
   remove(migration: string): Promise<void>;
+  transaction<T>(run: (tx: SQL) => Promise<T>): Promise<T>;
   close(): Promise<void>;
 }
 

package/src/core/random-name.ts

@@ -1,54 +1,20 @@
 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 = [
@@ -61,47 +27,13 @@ const nouns = [
   "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 {

package/src/drivers/mariadb.ts

@@ -1,45 +1,42 @@
-import { SQL } from "bun";
-import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
+import { type SQL } from "bun";
+import type { MigrationDriver } from "../core/driver.js";
+import { createSqlDriver } from "./shared.js";
 
-export function create(databaseUrl: string): MigrationDriver {
-  const db = new SQL(databaseUrl);
+async function checksumColumnExists(db: SQL): Promise<boolean> {
+  const rows = await db`SELECT column_name FROM information_schema.columns
+    WHERE table_schema = DATABASE()
+      AND table_name = 'migrations'
+      AND column_name = 'checksum'`;
+  return rows.length > 0;
+}
+
+async function uniqueIndexExists(db: SQL): Promise<boolean> {
+  const rows = await db`SELECT index_name FROM information_schema.statistics
+    WHERE table_schema = DATABASE()
+      AND table_name = 'migrations'
+      AND index_name = 'migrations_migration_unique'`;
+  return rows.length > 0;
+}
 
-  return {
-    async install() {
+export function create(databaseUrl: string): MigrationDriver {
+  return createSqlDriver(databaseUrl, {
+    async install(db) {
       await db`CREATE TABLE IF NOT EXISTS migrations (
         id INTEGER PRIMARY KEY AUTO_INCREMENT,
         migration VARCHAR(255) NOT NULL,
-        checksum VARCHAR(64)
+        checksum VARCHAR(64),
+        CONSTRAINT migrations_migration_unique UNIQUE (migration)
       )`;
-      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,
-        }),
-      );
+      if (!(await checksumColumnExists(db))) {
+        await db`ALTER TABLE migrations ADD COLUMN checksum VARCHAR(64)`;
+      }
+      if (!(await uniqueIndexExists(db))) {
+        await db`CREATE UNIQUE INDEX migrations_migration_unique ON migrations (migration)`;
+      }
     },
-
-    async record(migration: string, checksum: string) {
+    async record(db, migration, checksum) {
       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

@@ -1,11 +1,9 @@
-import { SQL } from "bun";
-import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
+import type { MigrationDriver } from "../core/driver.js";
+import { createSqlDriver } from "./shared.js";
 
 export function create(databaseUrl: string): MigrationDriver {
-  const db = new SQL(databaseUrl);
-
-  return {
-    async install() {
+  return createSqlDriver(databaseUrl, {
+    async install(db) {
       await db`CREATE TABLE IF NOT EXISTS migrations (
         id SERIAL PRIMARY KEY,
         migration VARCHAR(255) NOT NULL,
@@ -14,33 +12,10 @@ export function create(databaseUrl: string): MigrationDriver {
       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) {
+    async record(db, migration, checksum) {
       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/shared.ts

@@ -0,0 +1,35 @@
+import { SQL } from "bun";
+import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
+
+export interface SqlDialect {
+  install(db: SQL): Promise<void>;
+  record(db: SQL, migration: string, checksum: string): Promise<void>;
+}
+
+export function createSqlDriver(databaseUrl: string, dialect: SqlDialect): MigrationDriver {
+  const db = new SQL(databaseUrl);
+
+  return {
+    install: () => dialect.install(db),
+    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,
+        }),
+      );
+    },
+    record: (migration, checksum) => dialect.record(db, migration, checksum),
+    async setChecksum(migration, checksum) {
+      await db`UPDATE migrations SET checksum = ${checksum} WHERE migration = ${migration}`;
+    },
+    async remove(migration) {
+      await db`DELETE FROM migrations WHERE migration = ${migration}`;
+    },
+    transaction: (run) => db.begin(run),
+    async close() {
+      db.close({ timeout: 0 });
+    },
+  };
+}

package/src/drivers/sqlite.ts

@@ -1,11 +1,9 @@
-import { SQL } from "bun";
-import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
+import type { MigrationDriver } from "../core/driver.js";
+import { createSqlDriver } from "./shared.js";
 
 export function create(databaseUrl: string): MigrationDriver {
-  const db = new SQL(databaseUrl);
-
-  return {
-    async install() {
+  return createSqlDriver(databaseUrl, {
+    async install(db) {
       await db`CREATE TABLE IF NOT EXISTS migrations (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         migration TEXT NOT NULL,
@@ -20,32 +18,9 @@ export function create(databaseUrl: string): MigrationDriver {
       }
       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) {
+    async record(db, migration, checksum) {
       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 });
-    },
-  };
+  });
 }