bunsql-native-migrate 0.1.1 → 0.2.0

package/src/api/up.ts

@@ -1,69 +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 checksumEntries = await Promise.all(
-      allFiles.map(async (file) => [file, await checksumFile(path.join(listDir, file))] as const),
-    );
-    const checksums = new Map(checksumEntries);
+    return withMigrationLock(driver, lockTimeout, async () => {
+      const allFiles = await listFiles(listDir, MIGRATION_EXTENSIONS);
+      if (target !== undefined && !allFiles.includes(target)) {
+        throw new MigrationNotFoundError(target);
+      }
 
-    const executed = await driver.listExecuted();
-    const executedByName = new Map(executed.map((entry) => [entry.name, entry]));
+      const checksums = new Map(
+        await Promise.all(
+          allFiles.map(
+            async (file) => [file, await checksumFile(path.join(listDir, file))] as const,
+          ),
+        ),
+      );
 
-    for (const file of allFiles) {
-      const record = executedByName.get(file);
-      if (!record) continue;
+      const executed = await driver.listExecuted();
+      const executedByName = new Map(executed.map((entry) => [entry.name, entry]));
 
-      const checksum = checksums.get(file);
-      if (!checksum) 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 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/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,9 @@ 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>;
+  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/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,59 @@
-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 { createReservedLock, createSqlDriver } from "./shared.js";
 
-export function create(databaseUrl: string): MigrationDriver {
-  const db = new SQL(databaseUrl);
+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
+    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 });
-    },
-  };
+    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,11 +1,18 @@
-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 { createReservedLock, createSqlDriver } from "./shared.js";
 
-export function create(databaseUrl: string): MigrationDriver {
-  const db = new SQL(databaseUrl);
+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)];
+}
 
-  return {
-    async install() {
+export function create(databaseUrl: string): MigrationDriver {
+  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 +21,26 @@ 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 });
-    },
-  };
+    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})`;
+        },
+      ),
+  });
 }