bunsql-native-migrate 0.1.2 → 0.3.0

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/mark.ts

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { checksumFile, listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
+import { log } from "../core/console.js";
+import { type MarkOptions, type MarkResult, MigrationNotFoundError } from "./options.js";
+import { runWithDriver } from "./run-with-driver.js";
+
+export async function markMigrationsApplied(options: MarkOptions = {}): Promise<MarkResult> {
+  const listDir = resolveListDir(options.listDir);
+  const target = options.to;
+
+  return runWithDriver(options, async (driver) => {
+    await driver.install();
+
+    const allFiles = await listFiles(listDir, MIGRATION_EXTENSIONS);
+    if (target !== undefined && !allFiles.includes(target)) {
+      throw new MigrationNotFoundError(target);
+    }
+
+    const executed = await driver.listExecuted();
+    const executedNames = new Set(executed.map((entry) => entry.name));
+    let pending = allFiles.filter((file) => !executedNames.has(file));
+    if (target !== undefined) {
+      if (executedNames.has(target)) {
+        log({ text: `${target} is already applied.`, type: "info" });
+        return { marked: [] };
+      }
+      pending = pending.slice(0, pending.indexOf(target) + 1);
+    }
+
+    const marked: string[] = [];
+    for (const file of pending) {
+      const checksum = await checksumFile(path.join(listDir, file));
+      await driver.record(file, checksum);
+      marked.push(file);
+      log({ text: `${file} marked as applied`, type: "success" });
+    }
+    if (marked.length === 0) {
+      log({ text: "No pending migrations to mark.", type: "warn" });
+    }
+
+    return { marked };
+  });
+}

package/src/api/options.ts

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

package/src/api/run-step.ts

@@ -4,10 +4,12 @@ import type { MigrationDriver } from "../core/driver.js";
 export async function runMigrationStep(
   driver: MigrationDriver,
   step: (tx?: SQL) => Promise<void>,
-): Promise<void> {
+): Promise<number> {
+  const startedAt = performance.now();
   if (step.length > 0) {
     await driver.transaction((tx) => step(tx));
-    return;
+    return performance.now() - startedAt;
   }
   await step();
+  return performance.now() - startedAt;
 }

package/src/api/run-with-driver.ts

@@ -7,7 +7,10 @@ export async function runWithDriver<T>(
   run: (driver: MigrationDriver) => Promise<T>,
 ): Promise<T> {
   const url = getDatabaseUrl(options.databaseUrl);
-  const driver = await createDriver(url);
+  const driver = await createDriver(url, {
+    ...(options.tableName !== undefined ? { tableName: options.tableName } : {}),
+    ...(options.schema !== undefined ? { schema: options.schema } : {}),
+  });
   try {
     return await run(driver);
   } finally {

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,123 @@
 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 { formatDuration } from "../core/duration.js";
+import type { ExecutedMigration, MigrationDriver } from "../core/driver.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 { loadMigration } from "./load-migration.js";
+import { resolveLockTimeout, withMigrationLock } from "./lock.js";
 
-export async function migrateUp(options: MigrateOptions = {}): Promise<MigrateUpResult> {
+async function listExecutedForPlan(driver: MigrationDriver): Promise<ExecutedMigration[]> {
+  if ((await driver.trackingTableExists?.()) === false) {
+    return [];
+  }
+  return driver.listExecuted();
+}
+
+export async function migrateUp(options: MigrateUpOptions = {}): Promise<MigrateUpResult> {
   const listDir = resolveListDir(options.listDir);
+  const target = options.to;
+  const dryRun = options.dryRun ?? false;
+  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),
-      ),
-    );
-
-    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;
-
-      if (record.checksum === null) {
-        await driver.setChecksum(file, checksum);
-        log({ text: `${file} checksum saved (legacy record)`, type: "info" });
-        continue;
-      }
+    if (!dryRun) {
+      await driver.install();
+    }
 
-      if (record.checksum !== checksum) {
-        throw new ChecksumDriftError(file);
+    const run = async (): Promise<MigrateUpResult> => {
+      const allFiles = await listFiles(listDir, MIGRATION_EXTENSIONS);
+      if (target !== undefined && !allFiles.includes(target)) {
+        throw new MigrationNotFoundError(target);
       }
-    }
 
-    const pending = allFiles.filter((file) => !executedByName.has(file));
-    const applied: string[] = [];
+      const checksums = new Map(
+        await Promise.all(
+          allFiles.map(
+            async (file) => [file, await checksumFile(path.join(listDir, file))] as const,
+          ),
+        ),
+      );
 
-    if (pending.length === 0) {
-      log({ text: "No pending migrations.", type: "warn" });
-      return { applied };
-    }
+      const executed = dryRun ? await listExecutedForPlan(driver) : await driver.listExecuted();
+      const executedByName = new Map(executed.map((entry) => [entry.name, entry]));
 
-    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" });
+      for (const [file, checksum] of checksums) {
+        const record = executedByName.get(file);
+        if (!record) continue;
+
+        if (record.checksum === null) {
+          if (!dryRun) {
+            await driver.setChecksum(file, checksum);
+            log({ text: `${file} checksum saved (legacy record)`, type: "info" });
+          }
           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;
+
+        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 dryRun ? { applied: [], planned: [] } : { applied: [] };
+        }
+        pending = pending.slice(0, pending.indexOf(target) + 1);
       }
-    }
 
-    return { applied };
+      if (dryRun) {
+        log({ text: "Dry run — no changes will be made.", type: "info" });
+        if (pending.length === 0) {
+          log({ text: "No pending migrations.", type: "warn" });
+        }
+        for (const file of pending) {
+          log({ text: `${file} would be applied`, type: "info" });
+        }
+        return { applied: [], planned: pending };
+      }
+
+      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 { up } = await loadMigration(listDir, file);
+          if (up === null) {
+            log({ text: `${file} has no up() export, skipping`, type: "warn" });
+            continue;
+          }
+          const durationMs = await runMigrationStep(driver, up);
+          await driver.record(file, checksum);
+          applied.push(file);
+          log({ text: `${file} migrated up (${formatDuration(durationMs)})`, type: "success" });
+        } catch (error) {
+          log({ text: `${file} migration failed`, type: "error", error });
+          throw error;
+        }
+      }
+
+      return { applied };
+    };
+
+    if (dryRun) {
+      return run();
+    }
+    return withMigrationLock(driver, lockTimeout, run);
   });
 }

package/src/cli/main.ts

@@ -1,9 +1,13 @@
 #!/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 { initMigrations } from "../api/init.js";
+import { markMigrationsApplied } from "../api/mark.js";
+import { ChecksumDriftError, MigrationLockError, MigrationNotFoundError } from "../api/options.js";
+import { InvalidIdentifierError } from "../core/identifiers.js";
 import { log } from "../core/console.js";
 
 interface CliArgs {
@@ -11,6 +15,14 @@ interface CliArgs {
   positional: string[];
   dir?: string | undefined;
   git: boolean;
+  lang?: MigrationLang | undefined;
+  to?: string | undefined;
+  lockTimeout?: number | undefined;
+  table?: string | undefined;
+  schema?: string | undefined;
+  dryRun: boolean;
+  all: boolean;
+  strict: boolean;
   help: boolean;
 }
 
@@ -18,6 +30,14 @@ 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 table: string | undefined;
+  let schema: string | undefined;
+  let dryRun = false;
+  let all = false;
+  let strict = false;
   let help = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]!;
@@ -25,18 +45,77 @@ 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 === "--table") {
+      table = argv[++i];
+      if (table === undefined) {
+        log({ text: "--table requires a tracking table name", type: "error" });
+        usage(1);
+      }
+    } else if (arg === "--schema") {
+      schema = argv[++i];
+      if (schema === undefined) {
+        log({ text: "--schema requires a postgres schema name", type: "error" });
+        usage(1);
+      }
+    } else if (arg === "--all") {
+      all = true;
+    } else if (arg === "--dry-run") {
+      dryRun = 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,
+    table,
+    schema,
+    dryRun,
+    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 <init|up|down [n]|install|create [name]|mark [name]|status> [--dir <migrations-dir>] [--to <name>] [--lock-timeout <seconds>] [--table <name>] [--schema <name>] [--dry-run] [--all] [--lang <js|ts>] [--git] [--strict] [--help]",
     type: "info",
   });
   process.exit(exitCode);
@@ -44,6 +123,10 @@ function usage(exitCode: number): never {
 
 const args = parseArgs(process.argv.slice(2));
 const listDirOptions = args.dir ? { listDir: args.dir } : {};
+const tableOptions = {
+  ...(args.table !== undefined ? { tableName: args.table } : {}),
+  ...(args.schema !== undefined ? { schema: args.schema } : {}),
+};
 
 if (args.help) {
   usage(0);
@@ -52,34 +135,121 @@ if (args.help) {
 try {
   switch (args.command) {
     case "up": {
-      const { applied } = await migrateUp(listDirOptions);
+      const { applied, planned } = await migrateUp({
+        ...listDirOptions,
+        ...tableOptions,
+        ...(args.to ? { to: args.to } : {}),
+        ...(args.lockTimeout !== undefined ? { lockTimeout: args.lockTimeout } : {}),
+        ...(args.dryRun ? { dryRun: true } : {}),
+      });
+      if (planned !== undefined && planned.length > 0) {
+        log({ text: `Would apply ${planned.length} migration(s).`, type: "info" });
+      }
       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, planned } = await migrateDown({
+        ...listDirOptions,
+        ...tableOptions,
+        steps,
+        ...(args.dryRun ? { dryRun: true } : {}),
+      });
+      if (planned !== undefined && planned.length > 0) {
+        log({ text: `Would revert ${planned.length} migration(s).`, type: "info" });
+      }
+      if (reverted.length > 0) {
+        log({ text: `Reverted ${reverted.length} migration(s).`, type: "success" });
+      }
+      break;
+    }
+    case "init": {
+      await initMigrations({
+        ...listDirOptions,
+        ...(args.lang !== undefined ? { lang: args.lang } : {}),
+      });
       break;
     }
     case "install": {
-      await installMigrations(listDirOptions);
+      await installMigrations({ ...listDirOptions, ...tableOptions });
       break;
     }
     case "create": {
       const [name] = args.positional;
       await createMigrationCommand({
         ...(name ? { name } : {}),
+        ...(args.lang ? { lang: args.lang } : {}),
         git: args.git,
         ...listDirOptions,
       });
       break;
     }
+    case "mark": {
+      const [name] = args.positional;
+      if (args.all && name !== undefined) {
+        log({ text: "Use either --all or a migration file name, not both.", type: "error" });
+        usage(1);
+      }
+      if (!args.all && name === undefined) {
+        log({ text: "mark requires a migration file name or --all.", type: "error" });
+        usage(1);
+      }
+      const { marked } = await markMigrationsApplied({
+        ...listDirOptions,
+        ...tableOptions,
+        ...(name !== undefined ? { to: name } : {}),
+      });
+      if (marked.length > 0) {
+        log({ text: `Marked ${marked.length} migration(s) as applied.`, type: "success" });
+      }
+      break;
+    }
+    case "status": {
+      const { applied, pending } = await migrateStatus({ ...listDirOptions, ...tableOptions });
+      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 ||
+    error instanceof InvalidIdentifierError
+  ) {
     log({ text: error.message, type: "error" });
   } else {
     log({ text: "Migration command failed", type: "error", error });