bunsql-native-migrate 0.3.1 → 0.4.0

package/src/api/pending.ts

@@ -0,0 +1,58 @@
+import { listFiles, MIGRATION_EXTENSIONS } from "../core/fs.js";
+import { log } from "../core/console.js";
+import { MigrationNotFoundError } from "./options.js";
+
+export interface PendingToTargetResult {
+  pending: string[];
+  targetApplied: boolean;
+}
+
+interface ResolvePendingOptions {
+  allFiles: string[];
+  executedNames: string[];
+  target: string | undefined;
+}
+
+export function assertTargetInFiles(allFiles: readonly string[], target: string): void {
+  if (!allFiles.includes(target)) {
+    throw new MigrationNotFoundError(target);
+  }
+}
+
+export async function assertTargetOptions(
+  command: string,
+  listDir: string,
+  target: string | undefined,
+  steps: unknown,
+): Promise<void> {
+  if (target !== undefined && steps !== undefined) {
+    throw new Error(`Invalid ${command} options: "to" and "steps" cannot be combined`);
+  }
+  if (target !== undefined) {
+    assertTargetInFiles(await listFiles(listDir, MIGRATION_EXTENSIONS), target);
+  }
+}
+
+export function resolvePendingToTarget({
+  allFiles,
+  executedNames,
+  target,
+}: ResolvePendingOptions): PendingToTargetResult {
+  const executed = new Set(executedNames);
+
+  if (target !== undefined) {
+    assertTargetInFiles(allFiles, target);
+  }
+
+  let pending = allFiles.filter((file) => !executed.has(file));
+  let targetApplied = false;
+  if (target !== undefined) {
+    if (executed.has(target)) {
+      log({ text: `${target} is already applied.`, type: "info" });
+      targetApplied = true;
+    } else {
+      pending = pending.slice(0, pending.indexOf(target) + 1);
+    }
+  }
+  return { pending, targetApplied };
+}

package/src/api/redo.ts

@@ -0,0 +1,44 @@
+import { resolveListDir } from "../core/fs.js";
+import { log } from "../core/console.js";
+import { type RedoOptions, type RedoResult } from "./options.js";
+import { migrateDown, parseSteps } from "./down.js";
+import { migrateUp } from "./up.js";
+import { migrateStatus } from "./status.js";
+import { assertTargetOptions } from "./pending.js";
+
+export async function migrateRedo(options: RedoOptions = {}): Promise<RedoResult> {
+  const listDir = resolveListDir(options.listDir);
+  const target = options.to;
+  const steps = parseSteps(options.steps);
+
+  await assertTargetOptions("redo", listDir, target, options.steps);
+
+  const { applied } = await migrateStatus(options);
+  const lastApplied = applied.at(-1)?.name;
+  if (lastApplied === undefined) {
+    log({ text: "No migrations to redo.", type: "warn" });
+    return { reverted: [], applied: [] };
+  }
+
+  const appliedNames = applied.map((entry) => entry.name);
+  if (target !== undefined && !appliedNames.includes(target)) {
+    log({ text: `${target} is not applied — nothing to redo.`, type: "warn" });
+    return { reverted: [], applied: [] };
+  }
+
+  let reverted: string[] = [];
+  try {
+    ({ reverted } =
+      target !== undefined ? await migrateDown(options) : await migrateDown({ ...options, steps }));
+    const up = await migrateUp({ ...options, to: lastApplied });
+    return { reverted, applied: up.applied };
+  } catch (error) {
+    if (reverted.length > 0) {
+      log({
+        text: "Redo: the up phase failed — the rollbacks above stay reverted; run up to re-apply them",
+        type: "warn",
+      });
+    }
+    throw error;
+  }
+}

package/src/api/run-step.ts

@@ -1,15 +1,33 @@
 import { type SQL } from "bun";
 import type { MigrationDriver } from "../core/driver.js";
+import type { MigrationStepPlan } from "./load-migration.js";
 
 export async function runMigrationStep(
   driver: MigrationDriver,
-  step: (tx?: SQL) => Promise<void>,
+  plan: MigrationStepPlan,
 ): Promise<number> {
   const startedAt = performance.now();
-  if (step.length > 0) {
-    await driver.transaction((tx) => step(tx));
+  if (plan.noTransaction) {
+    await runOutsideTransaction(driver, plan.step);
+    return performance.now() - startedAt;
+  }
+  if (plan.step.length > 0) {
+    await driver.transaction((tx) => plan.step(tx));
     return performance.now() - startedAt;
   }
-  await step();
+  await plan.step();
   return performance.now() - startedAt;
 }
+
+function runOutsideTransaction(
+  driver: MigrationDriver,
+  step: (tx?: SQL) => Promise<void>,
+): Promise<void> {
+  const client = driver.client?.();
+  if (client === undefined) {
+    throw new Error(
+      "this driver does not expose a non-transactional client — the noTransaction marker is unsupported here",
+    );
+  }
+  return step(client);
+}

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

@@ -1,16 +1,21 @@
 import { getDatabaseUrl } from "../core/env.js";
-import { createDriver, type MigrationDriver } from "../core/driver.js";
+import type { MigrationDriver } from "../core/driver.js";
 import type { MigrateOptions } from "./options.js";
+import { connectDriver, resolveWaitTimeout } from "./wait.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, {
-    ...(options.tableName !== undefined ? { tableName: options.tableName } : {}),
-    ...(options.schema !== undefined ? { schema: options.schema } : {}),
-  });
+  const driver = await connectDriver(
+    url,
+    {
+      ...(options.tableName !== undefined ? { tableName: options.tableName } : {}),
+      ...(options.schema !== undefined ? { schema: options.schema } : {}),
+    },
+    resolveWaitTimeout(options.waitTimeout),
+  );
   try {
     return await run(driver);
   } finally {

package/src/api/up.ts

@@ -2,15 +2,11 @@ import path from "node:path";
 import { checksumFile, listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
 import { log } from "../core/console.js";
 import { formatDuration } from "../core/duration.js";
-import {
-  type MigrateUpOptions,
-  type MigrateUpResult,
-  ChecksumDriftError,
-  MigrationNotFoundError,
-} from "./options.js";
+import { type MigrateUpOptions, type MigrateUpResult, ChecksumDriftError } from "./options.js";
 import { runWithDriver } from "./run-with-driver.js";
 import { runMigrationStep } from "./run-step.js";
 import { loadMigration } from "./load-migration.js";
+import { resolvePendingToTarget } from "./pending.js";
 import { resolveLockTimeout, withMigrationLock } from "./lock.js";
 import { ensureTrackingTable, listExecutedForPlan } from "./tracking-table.js";
 
@@ -27,9 +23,6 @@ export async function migrateUp(options: MigrateUpOptions = {}): Promise<Migrate
 
     const run = async (): Promise<MigrateUpResult> => {
       const allFiles = await listFiles(listDir, MIGRATION_EXTENSIONS);
-      if (target !== undefined && !allFiles.includes(target)) {
-        throw new MigrationNotFoundError(target);
-      }
 
       const checksums = new Map(
         await Promise.all(
@@ -59,13 +52,13 @@ export async function migrateUp(options: MigrateUpOptions = {}): Promise<Migrate
         }
       }
 
-      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);
+      const { pending, targetApplied } = resolvePendingToTarget({
+        allFiles,
+        executedNames: executed.map((entry) => entry.name),
+        target,
+      });
+      if (targetApplied) {
+        return dryRun ? { applied: [], planned: [] } : { applied: [] };
       }
 
       if (dryRun) {

package/src/api/wait.ts

@@ -0,0 +1,67 @@
+import { log } from "../core/console.js";
+import { createDriver, type DriverTableOptions, type MigrationDriver } from "../core/driver.js";
+import { resolveSecondsOption } from "../core/duration.js";
+import { DatabaseWaitTimeoutError } from "./options.js";
+
+export const WAIT_RETRY_DELAY_MS = 500;
+
+export function resolveWaitTimeout(waitTimeout: number | undefined): number {
+  return resolveSecondsOption("waitTimeout", waitTimeout, 0);
+}
+
+export async function waitForDatabase<T>(
+  attempt: () => Promise<T>,
+  timeoutSeconds: number,
+  retryDelayMs: number = WAIT_RETRY_DELAY_MS,
+): Promise<T> {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let waitingLogged = false;
+  while (true) {
+    try {
+      return await attempt();
+    } catch (error) {
+      if (Date.now() >= deadline) {
+        throw new DatabaseWaitTimeoutError(timeoutSeconds, error);
+      }
+      if (!waitingLogged) {
+        log({ text: `database is not ready — waiting up to ${timeoutSeconds}s`, type: "info" });
+        waitingLogged = true;
+      }
+      await Bun.sleep(retryDelayMs);
+    }
+  }
+}
+
+async function connectProbed(
+  databaseUrl: string,
+  tableOptions: DriverTableOptions,
+): Promise<MigrationDriver> {
+  const driver = await createDriver(databaseUrl, tableOptions);
+  try {
+    await driver.transaction(async () => {});
+    return driver;
+  } catch (error) {
+    await driver.close().catch(() => undefined);
+    throw error;
+  }
+}
+
+async function assertDriverConfig(
+  databaseUrl: string,
+  tableOptions: DriverTableOptions,
+): Promise<void> {
+  const driver = await createDriver(databaseUrl, tableOptions);
+  await driver.close();
+}
+
+export async function connectDriver(
+  databaseUrl: string,
+  tableOptions: DriverTableOptions,
+  waitTimeout: number,
+): Promise<MigrationDriver> {
+  if (waitTimeout <= 0) {
+    return createDriver(databaseUrl, tableOptions);
+  }
+  await assertDriverConfig(databaseUrl, tableOptions);
+  return waitForDatabase(() => connectProbed(databaseUrl, tableOptions), waitTimeout);
+}

package/src/cli/main.ts

@@ -1,47 +1,145 @@
 #!/usr/bin/env bun
+import path from "node:path";
 import { migrateUp } from "../api/up.js";
-import { migrateDown } from "../api/down.js";
+import { migrateDown, parseSteps } from "../api/down.js";
+import { migrateRedo } from "../api/redo.js";
 import { migrateStatus } from "../api/status.js";
 import { installMigrations } from "../api/install.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 { resolveSecondsOption } from "../core/duration.js";
+import {
+  ChecksumDriftError,
+  DatabaseWaitTimeoutError,
+  MigrationLockError,
+  MigrationNotFoundError,
+} from "../api/options.js";
 import { InvalidIdentifierError } from "../core/identifiers.js";
 import { log } from "../core/console.js";
 
 interface CliArgs {
   command: string | undefined;
   positional: string[];
+  url?: string | undefined;
   dir?: string | undefined;
   git: boolean;
   lang?: MigrationLang | undefined;
   to?: string | undefined;
   lockTimeout?: number | undefined;
+  wait?: number | undefined;
   table?: string | undefined;
   schema?: string | undefined;
   dryRun: boolean;
   all: boolean;
   strict: boolean;
   help: boolean;
+  version: boolean;
+}
+
+type FlagKey = Exclude<keyof CliArgs, "command" | "positional" | "help" | "version">;
+
+const FLAG_NAMES: Record<FlagKey, string> = {
+  url: "--url",
+  dir: "--dir",
+  git: "--git",
+  lang: "--lang",
+  to: "--to",
+  lockTimeout: "--lock-timeout",
+  wait: "--wait",
+  table: "--table",
+  schema: "--schema",
+  dryRun: "--dry-run",
+  all: "--all",
+  strict: "--strict",
+};
+
+interface CommandSpec {
+  flags: ReadonlySet<FlagKey>;
+  positionalLimit: number;
+}
+
+const COMMAND_SPECS: Record<string, CommandSpec> = {
+  version: { flags: new Set<FlagKey>([]), positionalLimit: 0 },
+  up: {
+    flags: new Set(["url", "dir", "to", "lockTimeout", "wait", "table", "schema", "dryRun"]),
+    positionalLimit: 0,
+  },
+  down: {
+    flags: new Set(["url", "dir", "to", "wait", "table", "schema", "dryRun", "all"]),
+    positionalLimit: 1,
+  },
+  redo: {
+    flags: new Set(["url", "dir", "to", "lockTimeout", "wait", "table", "schema"]),
+    positionalLimit: 1,
+  },
+  init: { flags: new Set(["dir", "lang"]), positionalLimit: 0 },
+  install: { flags: new Set(["url", "dir", "wait", "table", "schema"]), positionalLimit: 0 },
+  create: { flags: new Set(["dir", "lang", "git"]), positionalLimit: 1 },
+  mark: { flags: new Set(["url", "dir", "wait", "table", "schema", "all"]), positionalLimit: 1 },
+  status: {
+    flags: new Set(["url", "dir", "wait", "table", "schema", "strict"]),
+    positionalLimit: 0,
+  },
+};
+
+function rejectDisallowedFlags(command: string, args: CliArgs): void {
+  const spec = COMMAND_SPECS[command];
+  if (spec === undefined) {
+    return;
+  }
+  const [extra] = args.positional.slice(spec.positionalLimit);
+  if (extra !== undefined) {
+    log({ text: `Unexpected argument for ${command}: ${extra}`, type: "error" });
+    usage(1);
+  }
+  for (const flag of Object.keys(FLAG_NAMES) as FlagKey[]) {
+    const value = args[flag];
+    if (value === undefined || value === false || spec.flags.has(flag)) {
+      continue;
+    }
+    log({ text: `${command} does not support ${FLAG_NAMES[flag]}.`, type: "error" });
+    usage(1);
+  }
+}
+
+function parseSecondsValue(flag: string, value: string | undefined): number {
+  try {
+    return resolveSecondsOption(flag, Number(value), 0);
+  } catch {
+    log({
+      text: `Invalid ${flag}: ${value ?? "(missing)"} (expected a non-negative integer of seconds)`,
+      type: "error",
+    });
+    usage(1);
+  }
 }
 
 function parseArgs(argv: string[]): CliArgs {
   const positional: string[] = [];
+  let url: string | undefined;
   let dir: string | undefined;
   let git = false;
   let lang: MigrationLang | undefined;
   let to: string | undefined;
   let lockTimeout: number | undefined;
+  let wait: number | undefined;
   let table: string | undefined;
   let schema: string | undefined;
   let dryRun = false;
   let all = false;
   let strict = false;
   let help = false;
+  let version = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]!;
-    if (arg === "--dir") {
+    if (arg === "--url") {
+      url = argv[++i];
+      if (url === undefined) {
+        log({ text: "--url requires a database URL", type: "error" });
+        usage(1);
+      }
+    } else if (arg === "--dir") {
       dir = argv[++i];
     } else if (arg === "--git") {
       git = true;
@@ -62,16 +160,9 @@ function parseArgs(argv: string[]): CliArgs {
         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;
+      lockTimeout = parseSecondsValue("--lock-timeout", argv[++i]);
+    } else if (arg === "--wait") {
+      wait = parseSecondsValue("--wait", argv[++i]);
     } else if (arg === "--table") {
       table = argv[++i];
       if (table === undefined) {
@@ -92,6 +183,8 @@ function parseArgs(argv: string[]): CliArgs {
       strict = true;
     } else if (arg === "--help" || arg === "-h") {
       help = true;
+    } else if (arg === "--version") {
+      version = true;
     } else {
       positional.push(arg);
     }
@@ -99,45 +192,72 @@ function parseArgs(argv: string[]): CliArgs {
   return {
     command: positional.shift(),
     positional,
+    url,
     dir,
     git,
     lang,
     to,
     lockTimeout,
+    wait,
     table,
     schema,
     dryRun,
     all,
     strict,
     help,
+    version,
   };
 }
 
 function usage(exitCode: number): never {
   log({
-    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]",
+    text: "Usage: bunsql-native-migrate <init|up|down [n]|redo [n]|install|create [name]|mark [name]|status|version> [--url <url>] [--dir <migrations-dir>] [--to <name>] [--lock-timeout <seconds>] [--wait <seconds>] [--table <name>] [--schema <name>] [--dry-run] [--all] [--lang <js|ts>] [--git] [--strict] [--version] [--help]",
     type: "info",
   });
   process.exit(exitCode);
 }
 
+async function printVersion(): Promise<void> {
+  const manifest = await Bun.file(path.resolve(import.meta.dir, "..", "..", "package.json")).json();
+  log({ text: String(manifest.version), type: "info" });
+}
+
 const args = parseArgs(process.argv.slice(2));
+const urlOptions = args.url !== undefined ? { databaseUrl: args.url } : {};
+const waitOptions = args.wait !== undefined && args.wait > 0 ? { waitTimeout: args.wait } : {};
 const listDirOptions = args.dir ? { listDir: args.dir } : {};
 const tableOptions = {
   ...(args.table !== undefined ? { tableName: args.table } : {}),
   ...(args.schema !== undefined ? { schema: args.schema } : {}),
 };
+const connectOptions = {
+  ...urlOptions,
+  ...listDirOptions,
+  ...tableOptions,
+  ...waitOptions,
+};
 
 if (args.help) {
   usage(0);
 }
 
+if (args.version) {
+  await printVersion();
+  process.exit(0);
+}
+
 try {
+  if (args.command !== undefined) {
+    rejectDisallowedFlags(args.command, args);
+  }
   switch (args.command) {
+    case "version": {
+      await printVersion();
+      break;
+    }
     case "up": {
       const { applied, planned } = await migrateUp({
-        ...listDirOptions,
-        ...tableOptions,
+        ...connectOptions,
         ...(args.to ? { to: args.to } : {}),
         ...(args.lockTimeout !== undefined ? { lockTimeout: args.lockTimeout } : {}),
         ...(args.dryRun ? { dryRun: true } : {}),
@@ -156,24 +276,30 @@ try {
         log({ text: "Use either --all or a number of steps, not both.", type: "error" });
         usage(1);
       }
+      if (args.to !== undefined && (args.all || stepsArg !== undefined)) {
+        log({
+          text: "Use either --to, --all, or a number of steps, not more than one of them.",
+          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) {
+        try {
+          steps = parseSteps(Number(stepsArg));
+        } catch {
           log({
             text: `Invalid step count: ${stepsArg} (expected a positive integer)`,
             type: "error",
           });
           usage(1);
         }
-        steps = parsed;
       }
       const { reverted, planned } = await migrateDown({
-        ...listDirOptions,
-        ...tableOptions,
-        steps,
+        ...connectOptions,
+        ...(args.to !== undefined ? { to: args.to } : { steps }),
         ...(args.dryRun ? { dryRun: true } : {}),
       });
       if (planned !== undefined && planned.length > 0) {
@@ -184,6 +310,35 @@ try {
       }
       break;
     }
+    case "redo": {
+      const [stepsArg] = args.positional;
+      if (stepsArg !== undefined && args.to !== undefined) {
+        log({ text: "Use either --to or a step count, not both.", type: "error" });
+        usage(1);
+      }
+      let steps: number | undefined;
+      if (stepsArg !== undefined) {
+        try {
+          steps = parseSteps(Number(stepsArg));
+        } catch {
+          log({
+            text: `Invalid step count: ${stepsArg} (expected a positive integer)`,
+            type: "error",
+          });
+          usage(1);
+        }
+      }
+      const { reverted } = await migrateRedo({
+        ...connectOptions,
+        ...(steps !== undefined ? { steps } : {}),
+        ...(args.to !== undefined ? { to: args.to } : {}),
+        ...(args.lockTimeout !== undefined ? { lockTimeout: args.lockTimeout } : {}),
+      });
+      if (reverted.length > 0) {
+        log({ text: `Redid ${reverted.length} migration(s).`, type: "success" });
+      }
+      break;
+    }
     case "init": {
       await initMigrations({
         ...listDirOptions,
@@ -192,7 +347,7 @@ try {
       break;
     }
     case "install": {
-      await installMigrations({ ...listDirOptions, ...tableOptions });
+      await installMigrations(connectOptions);
       break;
     }
     case "create": {
@@ -216,8 +371,7 @@ try {
         usage(1);
       }
       const { marked } = await markMigrationsApplied({
-        ...listDirOptions,
-        ...tableOptions,
+        ...connectOptions,
         ...(name !== undefined ? { to: name } : {}),
       });
       if (marked.length > 0) {
@@ -226,7 +380,7 @@ try {
       break;
     }
     case "status": {
-      const { applied, pending } = await migrateStatus({ ...listDirOptions, ...tableOptions });
+      const { applied, pending } = await migrateStatus(connectOptions);
       for (const entry of applied) {
         log({ text: `${entry.name} applied`, type: "info" });
       }
@@ -248,6 +402,7 @@ try {
     error instanceof ChecksumDriftError ||
     error instanceof MigrationNotFoundError ||
     error instanceof MigrationLockError ||
+    error instanceof DatabaseWaitTimeoutError ||
     error instanceof InvalidIdentifierError
   ) {
     log({ text: error.message, type: "error" });