bunsql-native-migrate 0.3.2 → 0.4.1

package/src/api/load-migration.ts

@@ -1,14 +1,21 @@
 import path from "node:path";
 import { type SQL } from "bun";
+import { MigrationFileMissingError } from "./options.js";
 
 export type MigrationStep = (tx?: SQL) => Promise<void>;
 
+export interface MigrationStepPlan {
+  step: MigrationStep;
+  noTransaction: boolean;
+}
+
 export interface MigrationFunctions {
-  up: MigrationStep | null;
-  down: MigrationStep | null;
+  up: MigrationStepPlan | null;
+  down: MigrationStepPlan | null;
 }
 
 const SQL_UP_SUFFIX = ".up.sql";
+const NO_TRANSACTION_DIRECTIVE = "-- bunsql-migrate:no-transaction";
 
 export function isSqlMigration(file: string): boolean {
   return file.endsWith(SQL_UP_SUFFIX);
@@ -27,19 +34,76 @@ function sqlFileStep(filePath: string): MigrationStep {
   };
 }
 
+function hasNoTransactionDirective(content: string): boolean {
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    if (!trimmed.startsWith("--")) return false;
+    if (trimmed === NO_TRANSACTION_DIRECTIVE) return true;
+  }
+  return false;
+}
+
+function hasParameterList(step: MigrationStep): boolean {
+  const source = step.toString();
+  const open = source.indexOf("(");
+  if (open === -1) return false;
+  let depth = 0;
+  for (let index = open; index < source.length; index++) {
+    const char = source[index];
+    if (char === "(") depth++;
+    else if (char === ")") {
+      depth--;
+      if (depth === 0) {
+        return source.slice(open + 1, index).trim().length > 0;
+      }
+    }
+  }
+  return false;
+}
+
+function assertExplicitTransactionMode(
+  file: string,
+  direction: "up" | "down",
+  step: MigrationStep,
+): void {
+  if (step.length > 0 || !hasParameterList(step)) return;
+  throw new Error(
+    `${file}: ${direction}() declares its parameter with a default value or as a rest parameter — ` +
+      `function.length is 0, so the step would silently run outside the migration transaction; ` +
+      `declare the parameter without a default (async (tx) => …) or add "export const noTransaction = true" to opt out explicitly`,
+  );
+}
+
+async function sqlFilePlan(filePath: string): Promise<MigrationStepPlan> {
+  const content = await Bun.file(filePath).text();
+  return {
+    step: sqlFileStep(filePath),
+    noTransaction: hasNoTransactionDirective(content),
+  };
+}
+
 export async function loadMigration(listDir: string, file: string): Promise<MigrationFunctions> {
+  const migrationPath = path.join(listDir, file);
+  if (!(await Bun.file(migrationPath).exists())) {
+    throw new MigrationFileMissingError(file);
+  }
+
   if (isSqlMigration(file)) {
-    const upPath = path.join(listDir, file);
     const downPath = path.join(listDir, sqlDownFile(file));
     return {
-      up: sqlFileStep(upPath),
-      down: (await Bun.file(downPath).exists()) ? sqlFileStep(downPath) : null,
+      up: await sqlFilePlan(migrationPath),
+      down: (await Bun.file(downPath).exists()) ? await sqlFilePlan(downPath) : null,
     };
   }
 
-  const mod = await import(path.join(listDir, file));
-  return {
-    up: typeof mod.up === "function" ? mod.up : null,
-    down: typeof mod.down === "function" ? mod.down : null,
-  };
+  const mod = await import(migrationPath);
+  const noTransaction = mod.noTransaction === true;
+  const up = typeof mod.up === "function" ? { step: mod.up, noTransaction } : null;
+  const down = typeof mod.down === "function" ? { step: mod.down, noTransaction } : null;
+  if (!noTransaction) {
+    if (up !== null) assertExplicitTransactionMode(file, "up", up.step);
+    if (down !== null) assertExplicitTransactionMode(file, "down", down.step);
+  }
+  return { up, down };
 }

package/src/api/lock.ts

@@ -1,4 +1,5 @@
 import { log } from "../core/console.js";
+import { resolveSecondsOption } from "../core/duration.js";
 import type { MigrationDriver } from "../core/driver.js";
 import { MigrationLockError } from "./options.js";
 
@@ -7,13 +8,7 @@ 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;
+  return resolveSecondsOption("lockTimeout", lockTimeout, DEFAULT_LOCK_TIMEOUT_SECONDS);
 }
 
 export async function withMigrationLock<T>(

package/src/api/mark.ts

@@ -1,5 +1,4 @@
-import path from "node:path";
-import { checksumFile, listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
+import { checksumFiles, listMigrationFiles, resolveListDir } from "../core/fs.js";
 import { log } from "../core/console.js";
 import { type MarkOptions, type MarkResult } from "./options.js";
 import { resolvePendingToTarget } from "./pending.js";
@@ -13,7 +12,7 @@ export async function markMigrationsApplied(options: MarkOptions = {}): Promise<
   return runWithDriver(options, async (driver) => {
     await ensureTrackingTable(driver);
 
-    const allFiles = await listFiles(listDir, MIGRATION_EXTENSIONS);
+    const allFiles = await listMigrationFiles(listDir);
     const executed = await driver.listExecuted();
 
     const { pending, targetApplied } = resolvePendingToTarget({
@@ -25,16 +24,14 @@ export async function markMigrationsApplied(options: MarkOptions = {}): Promise<
       return { marked: [] };
     }
 
-    const checksums = new Map(
-      await Promise.all(
-        pending.map(async (file) => [file, await checksumFile(path.join(listDir, file))] as const),
-      ),
-    );
+    const checksums = await checksumFiles(listDir, pending);
 
     const marked: string[] = [];
     for (const file of pending) {
       const checksum = checksums.get(file);
-      if (!checksum) continue;
+      if (checksum === undefined) {
+        throw new Error(`checksum for ${file} was not computed`);
+      }
       await driver.record(file, checksum);
       marked.push(file);
       log({ text: `${file} marked as applied`, type: "success" });

package/src/api/options.ts

@@ -5,6 +5,7 @@ export interface MigrateOptions {
   listDir?: string;
   tableName?: string;
   schema?: string;
+  waitTimeout?: number;
 }
 
 export interface MigrateUpOptions extends MigrateOptions {
@@ -15,9 +16,16 @@ export interface MigrateUpOptions extends MigrateOptions {
 
 export interface MigrateDownOptions extends MigrateOptions {
   steps?: number | "all";
+  to?: string;
   dryRun?: boolean;
 }
 
+export interface RedoOptions extends MigrateOptions {
+  steps?: number;
+  to?: string;
+  lockTimeout?: number;
+}
+
 export interface MarkOptions extends MigrateOptions {
   to?: string;
 }
@@ -32,6 +40,11 @@ export interface MigrateDownResult {
   planned?: string[];
 }
 
+export interface RedoResult {
+  reverted: string[];
+  applied: string[];
+}
+
 export interface MarkResult {
   marked: string[];
 }
@@ -63,6 +76,18 @@ export class MigrationNotFoundError extends Error {
   }
 }
 
+export class MigrationFileMissingError extends Error {
+  readonly file: string;
+
+  constructor(file: string) {
+    super(
+      `${file} is missing from the migrations directory — restore the file or remove its tracking record manually`,
+    );
+    this.name = "MigrationFileMissingError";
+    this.file = file;
+  }
+}
+
 export class MigrationLockError extends Error {
   readonly timeoutSeconds: number;
 
@@ -75,6 +100,17 @@ export class MigrationLockError extends Error {
   }
 }
 
+export class DatabaseWaitTimeoutError extends Error {
+  readonly timeoutSeconds: number;
+
+  constructor(timeoutSeconds: number, cause?: unknown) {
+    const reason = cause instanceof Error ? `: ${cause.message}` : "";
+    super(`database was not ready within ${timeoutSeconds}s${reason}`);
+    this.name = "DatabaseWaitTimeoutError";
+    this.timeoutSeconds = timeoutSeconds;
+  }
+}
+
 export class GitStageError extends Error {
   readonly file: string;
   readonly exitCode: number;
@@ -89,3 +125,26 @@ export class GitStageError extends Error {
     this.exitCode = exitCode;
   }
 }
+
+export const MIGRATION_NAME_MAX_LENGTH = 128;
+
+const MIGRATION_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+export class InvalidMigrationNameError extends Error {
+  readonly value: string;
+
+  constructor(value: string) {
+    super(
+      `Invalid migration name: "${value}" — expected letters, digits, hyphens and underscores only ` +
+        `(no path separators, dots or spaces), at most ${MIGRATION_NAME_MAX_LENGTH} characters`,
+    );
+    this.name = "InvalidMigrationNameError";
+    this.value = value;
+  }
+}
+
+export function validateMigrationName(name: string): void {
+  if (!MIGRATION_NAME_PATTERN.test(name) || name.length > MIGRATION_NAME_MAX_LENGTH) {
+    throw new InvalidMigrationNameError(name);
+  }
+}

package/src/api/pending.ts

@@ -1,3 +1,4 @@
+import { listMigrationFiles } from "../core/fs.js";
 import { log } from "../core/console.js";
 import { MigrationNotFoundError } from "./options.js";
 
@@ -12,6 +13,26 @@ interface ResolvePendingOptions {
   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 listMigrationFiles(listDir), target);
+  }
+}
+
 export function resolvePendingToTarget({
   allFiles,
   executedNames,
@@ -19,8 +40,8 @@ export function resolvePendingToTarget({
 }: ResolvePendingOptions): PendingToTargetResult {
   const executed = new Set(executedNames);
 
-  if (target !== undefined && !allFiles.includes(target)) {
-    throw new MigrationNotFoundError(target);
+  if (target !== undefined) {
+    assertTargetInFiles(allFiles, target);
   }
 
   let pending = allFiles.filter((file) => !executed.has(file));

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

@@ -1,4 +1,4 @@
-import { listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
+import { listMigrationFiles, resolveListDir } from "../core/fs.js";
 import type { MigrateOptions, MigrateStatusResult } from "./options.js";
 import { runWithDriver } from "./run-with-driver.js";
 import { ensureTrackingTable } from "./tracking-table.js";
@@ -9,7 +9,7 @@ export async function migrateStatus(options: MigrateOptions = {}): Promise<Migra
   return runWithDriver(options, async (driver) => {
     await ensureTrackingTable(driver);
 
-    const files = await listFiles(listDir, MIGRATION_EXTENSIONS);
+    const files = await listMigrationFiles(listDir);
     const executed = await driver.listExecuted();
     const appliedNames = new Set(executed.map((entry) => entry.name));
 

package/src/api/tracking-table.ts

@@ -13,3 +13,14 @@ export async function listExecutedForPlan(driver: MigrationDriver): Promise<Exec
   }
   return driver.listExecuted();
 }
+
+export async function loadExecutedHistory(
+  driver: MigrationDriver,
+  dryRun: boolean,
+): Promise<ExecutedMigration[]> {
+  if (dryRun) {
+    return listExecutedForPlan(driver);
+  }
+  await ensureTrackingTable(driver);
+  return driver.listExecuted();
+}

package/src/api/up.ts

@@ -1,5 +1,4 @@
-import path from "node:path";
-import { checksumFile, listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
+import { checksumFiles, listMigrationFiles, resolveListDir } from "../core/fs.js";
 import { log } from "../core/console.js";
 import { formatDuration } from "../core/duration.js";
 import { type MigrateUpOptions, type MigrateUpResult, ChecksumDriftError } from "./options.js";
@@ -8,7 +7,7 @@ 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";
+import { loadExecutedHistory } from "./tracking-table.js";
 
 export async function migrateUp(options: MigrateUpOptions = {}): Promise<MigrateUpResult> {
   const listDir = resolveListDir(options.listDir);
@@ -17,22 +16,10 @@ export async function migrateUp(options: MigrateUpOptions = {}): Promise<Migrate
   const lockTimeout = resolveLockTimeout(options.lockTimeout);
 
   return runWithDriver(options, async (driver) => {
-    if (!dryRun) {
-      await ensureTrackingTable(driver);
-    }
-
     const run = async (): Promise<MigrateUpResult> => {
-      const allFiles = await listFiles(listDir, MIGRATION_EXTENSIONS);
-
-      const checksums = new Map(
-        await Promise.all(
-          allFiles.map(
-            async (file) => [file, await checksumFile(path.join(listDir, file))] as const,
-          ),
-        ),
-      );
-
-      const executed = dryRun ? await listExecutedForPlan(driver) : await driver.listExecuted();
+      const allFiles = await listMigrationFiles(listDir);
+      const checksums = await checksumFiles(listDir, allFiles);
+      const executed = await loadExecutedHistory(driver, dryRun);
       const executedByName = new Map(executed.map((entry) => [entry.name, entry]));
 
       for (const [file, checksum] of checksums) {
@@ -81,7 +68,9 @@ export async function migrateUp(options: MigrateUpOptions = {}): Promise<Migrate
 
       for (const file of pending) {
         const checksum = checksums.get(file);
-        if (!checksum) continue;
+        if (checksum === undefined) {
+          throw new Error(`checksum for ${file} was not computed`);
+        }
         try {
           const { up } = await loadMigration(listDir, file);
           if (up === null) {

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/exit-codes.ts

@@ -0,0 +1,31 @@
+import {
+  ChecksumDriftError,
+  InvalidMigrationNameError,
+  MigrationLockError,
+} from "../api/options.js";
+import { InvalidIdentifierError } from "../core/identifiers.js";
+import { InvalidConfigError } from "../core/config.js";
+
+export const EXIT_SUCCESS = 0;
+export const EXIT_GENERIC = 1;
+export const EXIT_PENDING = 2;
+export const EXIT_CHECKSUM_DRIFT = 3;
+export const EXIT_LOCK_TIMEOUT = 4;
+export const EXIT_USAGE = 5;
+
+export function exitCodeForError(error: unknown): number {
+  if (error instanceof ChecksumDriftError) {
+    return EXIT_CHECKSUM_DRIFT;
+  }
+  if (error instanceof MigrationLockError) {
+    return EXIT_LOCK_TIMEOUT;
+  }
+  if (
+    error instanceof InvalidIdentifierError ||
+    error instanceof InvalidConfigError ||
+    error instanceof InvalidMigrationNameError
+  ) {
+    return EXIT_USAGE;
+  }
+  return EXIT_GENERIC;
+}