skills/docs/persistence/database/migration/src/runner/migration-runner/migration-runner.md

migration-runner

(no submodules)

Purpose

MigrationRunner is the top-level orchestrator for the migration package. It wires together the planner, executor, store, lock, and event bus into a single high-level API. Consumers create a runner with their migration list and store adapter, then call up() to apply pending migrations, down() to roll back, status() to inspect the current state, and validate() to verify migration metadata consistency before running.

Features

• up(options?) — plans and applies all pending migrations; respects advisory locks, AbortSignal, and dry-run mode.
• down(options?) — plans and rolls back the last N applied migrations.
• status() — returns combined status of all registered migrations.
• validate() — checks for duplicate IDs and returns structured validation errors.
• Injectable Clock, LoggerLike, EventBus, and MigrationLockAdapter.
• createMigrationRunner factory function for ergonomic construction.

Usage: Basic Example

import { MigrationRunner, MemoryMigrationStore } from "@suaveplan/migration";

const store = new MemoryMigrationStore();
const runner = new MigrationRunner({ migrations, store });
const result = await runner.up();
// result.applied lists migration IDs that were applied

Usage: Advanced Example

import { MigrationRunner, MemoryMigrationStore, MemoryMigrationLock } from "@suaveplan/migration";
import { EventBus } from "@suaveplan/events";

const store = new MemoryMigrationStore();
const lock = new MemoryMigrationLock();
const events = new EventBus<MigrationEventMap>();

events.on("migration:after", ({ migration, durationMs }) => {
  console.log(`Applied ${migration.id} in ${durationMs}ms`);
});

const runner = new MigrationRunner({ migrations, store, lock, events, checksumValidation: true });
await runner.up({ signal: abortController.signal });

API Reference

class MigrationRunner

Constructor: (config: MigrationRunnerConfig, clock?: Clock)

• config.migrations — array of Migration objects.
• config.store — MigrationStoreAdapter for ledger persistence.
• config.lock? — optional MigrationLockAdapter.
• config.logger? — optional LoggerLike for structured log output.
• config.events? — optional EventBus<MigrationEventMap>.
• config.dryRun? — default false.
• config.checksumValidation? — default true.

up(options?: RunOptions): Promise<MigrationResult>

Returns { applied, skipped, failed, direction: "up", dryRun }.

down(options?: RunOptions & { steps?: number }): Promise<MigrationResult>

Returns { applied, skipped, failed, direction: "down", dryRun }.

status(): Promise<MigrationStatusEntry[]>

Returns status for every registered migration sorted by id.

validate(): Promise<ValidationResult>

Returns { valid, errors }.

createMigrationRunner(config, clock?): MigrationRunner

Factory function — equivalent to new MigrationRunner(config, clock).

Implementation Notes

The buildContext() method provides a no-op execute/query implementation suitable for runners that do not need direct database access in migration functions (e.g. when the migration functions close over an external adapter). Consumers requiring SQL execution in migration functions should provide a custom context via a subclass.