@dotdo/postgres 0.1.0

package/src/migrations/runner.ts

@@ -0,0 +1,1459 @@
+/**
+ * Migration Runner
+ *
+ * Executes migrations against a PGLite database instance.
+ * Designed for postgres.do's unique multi-database model where
+ * each user gets their own Durable Object database.
+ *
+ * Key features:
+ * - Auto-migration on first connection to new databases
+ * - Idempotent execution (safe to run multiple times)
+ * - Transaction-based migrations with automatic rollback on failure
+ * - Advisory locks to prevent concurrent migrations
+ * - Checksum validation to detect modified migrations
+ *
+ * @module migrations/runner
+ */
+
+import type {
+  Migration,
+  MigrationResult,
+  BatchMigrationResult,
+  MigrationProgressEvent,
+  MigrationRunnerConfig,
+  MigrationEventListener,
+  MigrationEvent,
+  MigrationRecord,
+  SchemaVersion,
+  VersionComparison,
+  QueryExecutor,
+  MigrationLock,
+  RollbackOptions,
+  RollbackResult,
+  BatchRollbackResult,
+  RollbackEvent,
+  RollbackEventListener,
+  RollbackHistoryRecord,
+} from './types'
+import type { MigrationRegistry } from './registry'
+import { MigrationError } from '@dotdo/postgres-shared/errors'
+import { createLogger, LogLevel, type ILogger } from '@dotdo/postgres-shared'
+
+export { MigrationError }
+
+// Re-export RollbackProgressEvent for external use
+export type { RollbackProgressEvent } from './types'
+
+// Module-level logger for MigrationRunner
+// Level is DEBUG because the debug config flag gates whether log() is called at all.
+// The logger just provides structured output - the filtering happens at call site.
+const runnerLogger: ILogger = createLogger({
+  level: LogLevel.DEBUG,
+  prefix: '[MigrationRunner]',
+})
+
+/**
+ * Default runner configuration
+ */
+const DEFAULT_CONFIG: Required<Omit<MigrationRunnerConfig, 'onProgress'>> = {
+  tableName: '_migrations',
+  schema: 'public',
+  autoMigrate: true,
+  migrationTimeoutMs: 30000,
+  useLocking: true,
+  lockTimeoutMs: 5000,
+  debug: false,
+}
+
+/**
+ * SQL for creating the migrations table
+ */
+const CREATE_MIGRATIONS_TABLE_SQL = (tableName: string, schema: string) => `
+  CREATE TABLE IF NOT EXISTS "${schema}"."${tableName}" (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    version INTEGER NOT NULL UNIQUE,
+    checksum TEXT NOT NULL,
+    applied_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    execution_time_ms INTEGER NOT NULL DEFAULT 0,
+    status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'applied', 'failed', 'rolled_back'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_${tableName}_version ON "${schema}"."${tableName}" (version);
+  CREATE INDEX IF NOT EXISTS idx_${tableName}_status ON "${schema}"."${tableName}" (status);
+`
+
+/**
+ * SQL for creating the rollback history table
+ */
+const CREATE_ROLLBACK_HISTORY_TABLE_SQL = (tableName: string, schema: string) => `
+  CREATE TABLE IF NOT EXISTS "${schema}"."${tableName}_rollback_history" (
+    rollback_id TEXT PRIMARY KEY,
+    migration_id TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    rolled_back_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    execution_time_ms INTEGER NOT NULL DEFAULT 0,
+    previous_status TEXT NOT NULL,
+    initiated_by TEXT,
+    reason TEXT
+  );
+  CREATE INDEX IF NOT EXISTS idx_${tableName}_rollback_history_migration ON "${schema}"."${tableName}_rollback_history" (migration_id);
+  CREATE INDEX IF NOT EXISTS idx_${tableName}_rollback_history_version ON "${schema}"."${tableName}_rollback_history" (version);
+`
+
+/**
+ * Generate a unique rollback ID
+ */
+function generateRollbackId(): string {
+  const timestamp = Date.now().toString(36)
+  const random = Math.random().toString(36).substring(2, 8)
+  return `rollback_${timestamp}_${random}`
+}
+
+/**
+ * Calculate SHA-256 checksum for migration content
+ */
+async function calculateChecksum(content: string): Promise<string> {
+  const encoder = new TextEncoder()
+  const data = encoder.encode(content)
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+  const hashArray = Array.from(new Uint8Array(hashBuffer))
+  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+/**
+ * Generate a unique lock ID
+ */
+function generateLockId(): string {
+  const timestamp = Date.now().toString(36)
+  const random = Math.random().toString(36).substring(2, 8)
+  return `lock_${timestamp}_${random}`
+}
+
+/**
+ * Migration Runner
+ *
+ * Executes migrations against a database instance.
+ *
+ * @example
+ * ```typescript
+ * // Create a runner with a registry
+ * const runner = new MigrationRunner(pglite, registry, {
+ *   autoMigrate: true,
+ *   onProgress: (event) => console.log(event),
+ * })
+ *
+ * // Initialize (creates migrations table)
+ * await runner.initialize()
+ *
+ * // Run all pending migrations
+ * const result = await runner.migrate()
+ *
+ * // Get current schema version
+ * const version = await runner.getSchemaVersion()
+ * ```
+ */
+/** Concrete config type without undefined values */
+interface ResolvedMigrationRunnerConfig {
+  tableName: string
+  schema: string
+  autoMigrate: boolean
+  migrationTimeoutMs: number
+  useLocking: boolean
+  lockTimeoutMs: number
+  debug: boolean
+}
+
+export class MigrationRunner {
+  private executor: QueryExecutor
+  private registry: MigrationRegistry
+  private config: ResolvedMigrationRunnerConfig
+  private onProgress: ((event: MigrationProgressEvent) => void) | undefined
+  private initialized = false
+  private listeners: MigrationEventListener[] = []
+  private rollbackListeners: RollbackEventListener[] = []
+  private currentLock: MigrationLock | null = null
+
+  constructor(
+    executor: QueryExecutor,
+    registry: MigrationRegistry,
+    config: MigrationRunnerConfig = {}
+  ) {
+    this.executor = executor
+    this.registry = registry
+    // Type assertions needed because MigrationRunnerConfig has explicit `| undefined` in property types
+    // which isn't narrowed away by `??` operator even when defaults are provided
+    this.config = {
+      tableName: (config.tableName ?? DEFAULT_CONFIG.tableName) as string,
+      schema: (config.schema ?? DEFAULT_CONFIG.schema) as string,
+      autoMigrate: (config.autoMigrate ?? DEFAULT_CONFIG.autoMigrate) as boolean,
+      migrationTimeoutMs: (config.migrationTimeoutMs ?? DEFAULT_CONFIG.migrationTimeoutMs) as number,
+      useLocking: (config.useLocking ?? DEFAULT_CONFIG.useLocking) as boolean,
+      lockTimeoutMs: (config.lockTimeoutMs ?? DEFAULT_CONFIG.lockTimeoutMs) as number,
+      debug: (config.debug ?? DEFAULT_CONFIG.debug) as boolean,
+    }
+    this.onProgress = config.onProgress
+  }
+
+  /**
+   * Log debug message
+   */
+  private log(message: string, ...args: unknown[]): void {
+    if (this.config.debug) {
+      runnerLogger.debug(message, args.length > 0 ? { args } : undefined)
+    }
+  }
+
+  /**
+   * Emit a migration event
+   */
+  private async emitEvent(event: Omit<MigrationEvent, 'timestamp'>): Promise<void> {
+    const fullEvent: MigrationEvent = {
+      ...event,
+      timestamp: new Date(),
+    }
+
+    for (const listener of this.listeners) {
+      try {
+        await listener(fullEvent)
+      } catch (error) {
+        runnerLogger.error('Event listener error', {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+  }
+
+  /**
+   * Add an event listener
+   */
+  onEvent(listener: MigrationEventListener): () => void {
+    this.listeners.push(listener)
+    return () => {
+      const index = this.listeners.indexOf(listener)
+      if (index >= 0) {
+        this.listeners.splice(index, 1)
+      }
+    }
+  }
+
+  /**
+   * Emit a rollback event
+   */
+  private async emitRollbackEvent(event: Omit<RollbackEvent, 'timestamp'>): Promise<void> {
+    const fullEvent: RollbackEvent = {
+      ...event,
+      timestamp: new Date(),
+    }
+
+    for (const listener of this.rollbackListeners) {
+      try {
+        await listener(fullEvent)
+      } catch (error) {
+        runnerLogger.error('Rollback event listener error', {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+  }
+
+  /**
+   * Add a rollback event listener
+   */
+  onRollbackEvent(listener: RollbackEventListener): () => void {
+    this.rollbackListeners.push(listener)
+    return () => {
+      const index = this.rollbackListeners.indexOf(listener)
+      if (index >= 0) {
+        this.rollbackListeners.splice(index, 1)
+      }
+    }
+  }
+
+  /**
+   * Get the full qualified table name
+   */
+  private getTableName(): string {
+    return `"${this.config.schema}"."${this.config.tableName}"`
+  }
+
+  /**
+   * Initialize the migration runner
+   *
+   * Creates the migrations table and rollback history table if they don't exist.
+   * Safe to call multiple times.
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return
+    }
+
+    this.log('Initializing migrations table')
+
+    try {
+      await this.executor.query(
+        CREATE_MIGRATIONS_TABLE_SQL(this.config.tableName, this.config.schema)
+      )
+      await this.executor.query(
+        CREATE_ROLLBACK_HISTORY_TABLE_SQL(this.config.tableName, this.config.schema)
+      )
+      this.initialized = true
+      await this.emitEvent({ type: 'table_created' })
+      this.log('Migrations table ready')
+    } catch (error) {
+      this.log('Error creating migrations table:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Get the rollback history table name
+   */
+  private getRollbackHistoryTableName(): string {
+    return `"${this.config.schema}"."${this.config.tableName}_rollback_history"`
+  }
+
+  /**
+   * Acquire a migration lock
+   *
+   * Uses PostgreSQL advisory locks to prevent concurrent migrations.
+   * This is important in Cloudflare Workers where multiple requests
+   * might hit the same DO simultaneously.
+   */
+  private async acquireLock(): Promise<boolean> {
+    if (!this.config.useLocking) {
+      return true
+    }
+
+    const lockId = generateLockId()
+    const lockKey = 12345 // Fixed lock key for migrations
+
+    try {
+      // Try to acquire an exclusive session-level advisory lock
+      const result = await this.executor.query<{ pg_try_advisory_lock: boolean }>(
+        `SELECT pg_try_advisory_lock($1)`,
+        [lockKey]
+      )
+
+      if (result.rows[0]?.pg_try_advisory_lock) {
+        this.currentLock = {
+          acquired: true,
+          lockId,
+          acquiredAt: new Date(),
+          expiresAt: new Date(Date.now() + this.config.lockTimeoutMs),
+        }
+        await this.emitEvent({ type: 'lock_acquired', lock: this.currentLock })
+        this.log('Lock acquired:', lockId)
+        return true
+      }
+
+      return false
+    } catch (error) {
+      // PGLite might not support advisory locks, continue without locking
+      this.log('Advisory lock not available, continuing without lock')
+      return true
+    }
+  }
+
+  /**
+   * Release the migration lock
+   */
+  private async releaseLock(): Promise<void> {
+    if (!this.config.useLocking || !this.currentLock?.acquired) {
+      return
+    }
+
+    const lockKey = 12345
+
+    try {
+      await this.executor.query(`SELECT pg_advisory_unlock($1)`, [lockKey])
+      await this.emitEvent({ type: 'lock_released', lock: this.currentLock })
+      this.log('Lock released:', this.currentLock.lockId)
+    } catch {
+      // Ignore unlock errors
+    } finally {
+      this.currentLock = null
+    }
+  }
+
+  /**
+   * Get the current schema version and all migration records
+   */
+  async getSchemaVersion(): Promise<SchemaVersion> {
+    await this.initialize()
+
+    const result = await this.executor.query<MigrationRecord>(
+      `SELECT id, name, version, checksum,
+              applied_at::text as applied_at,
+              execution_time_ms, status
+       FROM ${this.getTableName()}
+       ORDER BY version ASC`
+    )
+
+    const migrations = result.rows
+    const appliedMigrations = migrations.filter((m) => m.status === 'applied')
+
+    const currentVersion =
+      appliedMigrations.length > 0
+        ? Math.max(...appliedMigrations.map((m) => m.version))
+        : 0
+
+    const lastApplied = appliedMigrations.reduce<MigrationRecord | null>(
+      (latest, m) => (!latest || m.applied_at > latest.applied_at ? m : latest),
+      null
+    )
+
+    return {
+      currentVersion,
+      appliedCount: appliedMigrations.length,
+      lastMigrationAt: lastApplied?.applied_at ?? null,
+      migrations,
+    }
+  }
+
+  /**
+   * Compare current schema version against the registry
+   */
+  async compareVersion(): Promise<VersionComparison> {
+    const schemaVersion = await this.getSchemaVersion()
+    const targetVersion = this.registry.getLatestVersion()
+
+    const appliedVersions = new Set(
+      schemaVersion.migrations
+        .filter((m) => m.status === 'applied')
+        .map((m) => m.version)
+    )
+
+    // Find missing versions
+    const missingVersions: number[] = []
+    for (const version of this.registry.getMigrationVersions()) {
+      if (!appliedVersions.has(version)) {
+        missingVersions.push(version)
+      }
+    }
+
+    return {
+      current: schemaVersion.currentVersion,
+      target: targetVersion,
+      needsMigration: missingVersions.length > 0,
+      pendingCount: missingVersions.length,
+      missingVersions,
+    }
+  }
+
+  /**
+   * Get a migration record by ID
+   */
+  async getMigrationRecord(id: string): Promise<MigrationRecord | null> {
+    await this.initialize()
+
+    const result = await this.executor.query<MigrationRecord>(
+      `SELECT id, name, version, checksum,
+              applied_at::text as applied_at,
+              execution_time_ms, status
+       FROM ${this.getTableName()}
+       WHERE id = $1`,
+      [id]
+    )
+
+    return result.rows[0] ?? null
+  }
+
+  /**
+   * Check if a migration has been applied
+   */
+  async isMigrationApplied(id: string): Promise<boolean> {
+    const record = await this.getMigrationRecord(id)
+    return record?.status === 'applied'
+  }
+
+  /**
+   * Apply a single migration
+   */
+  private async applyMigration(
+    migration: Migration,
+    index: number,
+    total: number
+  ): Promise<MigrationResult> {
+    const checksum = await calculateChecksum(migration.up)
+    const existing = await this.getMigrationRecord(migration.id)
+
+    // Check if already applied
+    if (existing && existing.status === 'applied') {
+      // Validate checksum
+      if (existing.checksum !== checksum) {
+        const error = `Migration checksum mismatch. Expected: ${existing.checksum}, Got: ${checksum}. This may indicate the migration content has changed.`
+        this.log(`Migration ${migration.id} checksum mismatch`)
+        return {
+          success: false,
+          id: migration.id,
+          executionTimeMs: 0,
+          error,
+        }
+      }
+
+      // Already applied, skip
+      this.onProgress?.({
+        migration,
+        index,
+        total,
+        phase: 'skipped',
+      })
+
+      await this.emitEvent({
+        type: 'migration_skipped',
+        migration,
+      })
+
+      return {
+        success: true,
+        id: migration.id,
+        executionTimeMs: 0,
+        skipped: true,
+      }
+    }
+
+    // Emit start events
+    this.onProgress?.({
+      migration,
+      index,
+      total,
+      phase: 'starting',
+    })
+
+    await this.emitEvent({
+      type: 'migration_started',
+      migration,
+    })
+
+    const startTime = performance.now()
+
+    try {
+      // Begin transaction if migration is transactional
+      if (migration.transactional !== false) {
+        await this.executor.query('BEGIN')
+      }
+
+      // Execute migration SQL
+      this.onProgress?.({
+        migration,
+        index,
+        total,
+        phase: 'executing',
+      })
+
+      await this.executor.query(migration.up)
+
+      // Record the migration
+      await this.executor.query(
+        `INSERT INTO ${this.getTableName()} (id, name, version, checksum, execution_time_ms, status)
+         VALUES ($1, $2, $3, $4, $5, 'applied')
+         ON CONFLICT (id) DO UPDATE SET
+           status = 'applied',
+           execution_time_ms = $5,
+           applied_at = CURRENT_TIMESTAMP`,
+        [
+          migration.id,
+          migration.name,
+          migration.version,
+          checksum,
+          Math.round(performance.now() - startTime),
+        ]
+      )
+
+      // Commit transaction
+      if (migration.transactional !== false) {
+        await this.executor.query('COMMIT')
+      }
+
+      const executionTimeMs = Math.round(performance.now() - startTime)
+
+      const result: MigrationResult = {
+        success: true,
+        id: migration.id,
+        executionTimeMs,
+      }
+
+      // Emit completion events
+      this.onProgress?.({
+        migration,
+        index,
+        total,
+        phase: 'completed',
+        durationMs: executionTimeMs,
+      })
+
+      await this.emitEvent({
+        type: 'migration_completed',
+        migration,
+        result,
+      })
+
+      this.log(`Migration ${migration.id} applied in ${executionTimeMs}ms`)
+
+      return result
+    } catch (error) {
+      // Rollback on failure
+      if (migration.transactional !== false) {
+        try {
+          await this.executor.query('ROLLBACK')
+        } catch {
+          // Ignore rollback errors
+        }
+      }
+
+      const executionTimeMs = Math.round(performance.now() - startTime)
+      const errorMessage = error instanceof Error ? error.message : String(error)
+
+      // Record failed migration
+      try {
+        await this.executor.query(
+          `INSERT INTO ${this.getTableName()} (id, name, version, checksum, execution_time_ms, status)
+           VALUES ($1, $2, $3, $4, $5, 'failed')
+           ON CONFLICT (id) DO UPDATE SET
+             status = 'failed',
+             execution_time_ms = $5,
+             applied_at = CURRENT_TIMESTAMP`,
+          [migration.id, migration.name, migration.version, checksum, executionTimeMs]
+        )
+      } catch {
+        // Ignore recording errors
+      }
+
+      const result: MigrationResult = {
+        success: false,
+        id: migration.id,
+        executionTimeMs,
+        error: errorMessage,
+      }
+
+      // Emit failure events
+      this.onProgress?.({
+        migration,
+        index,
+        total,
+        phase: 'failed',
+        durationMs: executionTimeMs,
+        error: errorMessage,
+      })
+
+      await this.emitEvent({
+        type: 'migration_failed',
+        migration,
+        result,
+        error: error instanceof Error ? error : new Error(errorMessage),
+      })
+
+      this.log(`Migration ${migration.id} failed:`, errorMessage)
+
+      return result
+    }
+  }
+
+  /**
+   * Run all pending migrations
+   *
+   * This is the main entry point for migration execution.
+   * Migrations are run in version order, stopping on first failure.
+   */
+  async migrate(): Promise<BatchMigrationResult> {
+    await this.initialize()
+
+    // Acquire lock
+    const lockAcquired = await this.acquireLock()
+    if (!lockAcquired) {
+      throw new MigrationError('Failed to acquire migration lock - another migration may be in progress')
+    }
+
+    try {
+      const startVersion = (await this.getSchemaVersion()).currentVersion
+      const startTime = performance.now()
+
+      // Get pending migrations
+      const comparison = await this.compareVersion()
+      if (!comparison.needsMigration) {
+        return {
+          success: true,
+          fromVersion: startVersion,
+          toVersion: startVersion,
+          durationMs: 0,
+          results: [],
+          migrationsRun: 0,
+          migrationsSkipped: 0,
+        }
+      }
+
+      // Get migrations to run
+      const pendingMigrations = this.registry
+        .getMigrations()
+        .filter((m) => comparison.missingVersions.includes(m.version))
+
+      await this.emitEvent({
+        type: 'batch_started',
+        metadata: {
+          count: pendingMigrations.length,
+          versions: pendingMigrations.map((m) => m.version),
+        },
+      })
+
+      // Run migrations
+      const results: MigrationResult[] = []
+      let migrationsRun = 0
+      let migrationsSkipped = 0
+
+      for (let i = 0; i < pendingMigrations.length; i++) {
+        const migration = pendingMigrations[i]
+        if (!migration) continue
+        const result = await this.applyMigration(migration, i, pendingMigrations.length)
+        results.push(result)
+
+        if (result.skipped) {
+          migrationsSkipped++
+        } else if (result.success) {
+          migrationsRun++
+        } else {
+          // Stop on failure
+          break
+        }
+      }
+
+      const durationMs = Math.round(performance.now() - startTime)
+      const endVersion = (await this.getSchemaVersion()).currentVersion
+      const success = results.every((r) => r.success)
+
+      const batchResult: BatchMigrationResult = {
+        success,
+        fromVersion: startVersion,
+        toVersion: endVersion,
+        durationMs,
+        results,
+        migrationsRun,
+        migrationsSkipped,
+      }
+
+      await this.emitEvent({
+        type: success ? 'batch_completed' : 'batch_failed',
+        batchResult,
+      })
+
+      return batchResult
+    } finally {
+      await this.releaseLock()
+    }
+  }
+
+  /**
+   * Migrate up to a specific version
+   */
+  async migrateToVersion(targetVersion: number): Promise<BatchMigrationResult> {
+    await this.initialize()
+
+    const lockAcquired = await this.acquireLock()
+    if (!lockAcquired) {
+      throw new MigrationError('Failed to acquire migration lock')
+    }
+
+    try {
+      const schemaVersion = await this.getSchemaVersion()
+      const startVersion = schemaVersion.currentVersion
+      const startTime = performance.now()
+
+      // Get migrations up to target version that haven't been applied
+      const appliedIds = new Set(
+        schemaVersion.migrations
+          .filter((m) => m.status === 'applied')
+          .map((m) => m.id)
+      )
+
+      const migrationsToRun = this.registry
+        .getMigrationsUpTo(targetVersion)
+        .filter((m) => !appliedIds.has(m.id))
+
+      if (migrationsToRun.length === 0) {
+        return {
+          success: true,
+          fromVersion: startVersion,
+          toVersion: startVersion,
+          durationMs: 0,
+          results: [],
+          migrationsRun: 0,
+          migrationsSkipped: 0,
+        }
+      }
+
+      // Run migrations
+      const results: MigrationResult[] = []
+      let migrationsRun = 0
+      let migrationsSkipped = 0
+
+      for (let i = 0; i < migrationsToRun.length; i++) {
+        const migration = migrationsToRun[i]
+        if (!migration) continue
+        const result = await this.applyMigration(migration, i, migrationsToRun.length)
+        results.push(result)
+
+        if (result.skipped) {
+          migrationsSkipped++
+        } else if (result.success) {
+          migrationsRun++
+        } else {
+          break
+        }
+      }
+
+      const durationMs = Math.round(performance.now() - startTime)
+      const endVersion = (await this.getSchemaVersion()).currentVersion
+
+      return {
+        success: results.every((r) => r.success),
+        fromVersion: startVersion,
+        toVersion: endVersion,
+        durationMs,
+        results,
+        migrationsRun,
+        migrationsSkipped,
+      }
+    } finally {
+      await this.releaseLock()
+    }
+  }
+
+  /**
+   * Check if a migration is reversible
+   *
+   * A migration is reversible if:
+   * 1. It has down SQL defined
+   * 2. isReversible is not explicitly set to false
+   */
+  isReversible(migration: Migration): boolean {
+    if (!migration.down) {
+      return false
+    }
+    // If isReversible is explicitly set, use that value
+    // Otherwise, default to true if down SQL exists
+    return migration.isReversible !== false
+  }
+
+  /**
+   * Record a rollback in the history table
+   */
+  private async recordRollbackHistory(
+    rollbackId: string,
+    migration: Migration,
+    previousStatus: string,
+    executionTimeMs: number,
+    reason?: string
+  ): Promise<void> {
+    try {
+      await this.executor.query(
+        `INSERT INTO ${this.getRollbackHistoryTableName()}
+         (rollback_id, migration_id, version, execution_time_ms, previous_status, reason)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [rollbackId, migration.id, migration.version, executionTimeMs, previousStatus, reason ?? null]
+      )
+    } catch (error) {
+      this.log('Failed to record rollback history:', error)
+      // Don't throw - history recording is non-critical
+    }
+  }
+
+  /**
+   * Get rollback history
+   */
+  async getRollbackHistory(): Promise<RollbackHistoryRecord[]> {
+    await this.initialize()
+
+    const result = await this.executor.query<RollbackHistoryRecord>(
+      `SELECT rollback_id, migration_id, version,
+              rolled_back_at::text as rolled_back_at,
+              execution_time_ms, previous_status, initiated_by, reason
+       FROM ${this.getRollbackHistoryTableName()}
+       ORDER BY rolled_back_at DESC`
+    )
+
+    return result.rows
+  }
+
+  /**
+   * Plan a rollback operation
+   *
+   * Returns what would be rolled back without making changes.
+   * Useful for dry-run mode.
+   */
+  async planRollback(options: RollbackOptions): Promise<{
+    migrations: Migration[]
+    blockers: Array<{ id: string; version: number; reason: string }>
+  }> {
+    await this.initialize()
+
+    const schemaVersion = await this.getSchemaVersion()
+    const { toVersion, force = false } = options
+
+    // Get migrations to rollback (in reverse order)
+    const recordsToRollback = schemaVersion.migrations
+      .filter((m) => m.status === 'applied' && m.version > toVersion)
+      .sort((a, b) => b.version - a.version)
+
+    const migrations: Migration[] = []
+    const blockers: Array<{ id: string; version: number; reason: string }> = []
+
+    for (const record of recordsToRollback) {
+      const migration = this.registry.getMigration(record.id)
+
+      if (!migration) {
+        blockers.push({
+          id: record.id,
+          version: record.version,
+          reason: 'Migration not found in registry',
+        })
+        continue
+      }
+
+      if (!migration.down) {
+        blockers.push({
+          id: migration.id,
+          version: migration.version,
+          reason: 'No down SQL defined',
+        })
+        if (!force) continue
+      }
+
+      if (!this.isReversible(migration) && !force) {
+        blockers.push({
+          id: migration.id,
+          version: migration.version,
+          reason: 'Migration marked as non-reversible',
+        })
+        continue
+      }
+
+      migrations.push(migration)
+    }
+
+    return { migrations, blockers }
+  }
+
+  /**
+   * Rollback the last migration
+   *
+   * Enhanced version with dry-run and force support.
+   *
+   * @param options Optional rollback options
+   */
+  async rollbackLast(options: { dryRun?: boolean; force?: boolean; reason?: string } = {}): Promise<RollbackResult | null> {
+    await this.initialize()
+
+    const { dryRun = false, force = false, reason } = options
+
+    const schemaVersion = await this.getSchemaVersion()
+    const lastApplied = schemaVersion.migrations
+      .filter((m) => m.status === 'applied')
+      .sort((a, b) => b.version - a.version)[0]
+
+    if (!lastApplied) {
+      this.log('No migrations to rollback')
+      return null
+    }
+
+    const migration = this.registry.getMigration(lastApplied.id)
+    if (!migration) {
+      throw new MigrationError(`Migration ${lastApplied.id} not found in registry`)
+    }
+
+    if (!migration.down) {
+      throw new MigrationError(`Migration ${lastApplied.id} has no rollback SQL defined`)
+    }
+
+    if (!this.isReversible(migration) && !force) {
+      throw new MigrationError(
+        `Migration ${lastApplied.id} is marked as non-reversible. Use force=true to override.`
+      )
+    }
+
+    // Dry run - return what would happen without making changes
+    if (dryRun) {
+      return {
+        success: true,
+        id: migration.id,
+        version: migration.version,
+        executionTimeMs: 0,
+        isDryRun: true,
+      }
+    }
+
+    const lockAcquired = await this.acquireLock()
+    if (!lockAcquired) {
+      throw new MigrationError('Failed to acquire migration lock')
+    }
+
+    const rollbackId = generateRollbackId()
+    const startTime = performance.now()
+
+    try {
+      await this.emitRollbackEvent({
+        type: 'rollback_started',
+        migration,
+      })
+
+      // Execute rollback
+      await this.executor.query('BEGIN')
+
+      try {
+        await this.executor.query(migration.down)
+
+        // Update migration status
+        await this.executor.query(
+          `UPDATE ${this.getTableName()}
+           SET status = 'rolled_back', applied_at = CURRENT_TIMESTAMP
+           WHERE id = $1`,
+          [migration.id]
+        )
+
+        await this.executor.query('COMMIT')
+
+        const executionTimeMs = Math.round(performance.now() - startTime)
+
+        // Record in history
+        await this.recordRollbackHistory(
+          rollbackId,
+          migration,
+          lastApplied.status,
+          executionTimeMs,
+          reason
+        )
+
+        const result: RollbackResult = {
+          success: true,
+          id: migration.id,
+          version: migration.version,
+          executionTimeMs,
+        }
+
+        await this.emitEvent({
+          type: 'migration_rolled_back',
+          migration,
+        })
+
+        await this.emitRollbackEvent({
+          type: 'rollback_completed',
+          migration,
+          result,
+        })
+
+        this.log(`Rolled back migration ${migration.id} in ${executionTimeMs}ms`)
+
+        return result
+      } catch (error) {
+        await this.executor.query('ROLLBACK')
+
+        const executionTimeMs = Math.round(performance.now() - startTime)
+        const errorMessage = error instanceof Error ? error.message : String(error)
+
+        const result: RollbackResult = {
+          success: false,
+          id: migration.id,
+          version: migration.version,
+          executionTimeMs,
+          error: errorMessage,
+        }
+
+        await this.emitRollbackEvent({
+          type: 'rollback_failed',
+          migration,
+          result,
+          error: error instanceof Error ? error : new Error(errorMessage),
+        })
+
+        throw new MigrationError(
+          `Rollback failed for migration ${migration.id}: ${errorMessage}`,
+          {
+            migrationId: migration.id,
+            phase: 'rollback',
+            cause: error instanceof Error ? error : undefined,
+          }
+        )
+      }
+    } finally {
+      await this.releaseLock()
+    }
+  }
+
+  /**
+   * Rollback to a specific version
+   *
+   * Enhanced version with dry-run, force mode, and comprehensive error handling.
+   * Rolls back all migrations after the specified version in reverse order.
+   *
+   * @param options Rollback options including target version, dry-run, and force flags
+   */
+  async rollback(options: RollbackOptions): Promise<BatchRollbackResult> {
+    await this.initialize()
+
+    const { toVersion, dryRun = false, force = false, onProgress } = options
+
+    const lockAcquired = await this.acquireLock()
+    if (!lockAcquired) {
+      throw new MigrationError('Failed to acquire migration lock')
+    }
+
+    try {
+      const schemaVersion = await this.getSchemaVersion()
+      const startVersion = schemaVersion.currentVersion
+      const startTime = performance.now()
+
+      // Already at or below target version
+      if (startVersion <= toVersion) {
+        return {
+          success: true,
+          fromVersion: startVersion,
+          toVersion: startVersion,
+          durationMs: 0,
+          results: [],
+          rolledBackCount: 0,
+          skippedCount: 0,
+          isDryRun: dryRun,
+        }
+      }
+
+      // Plan the rollback
+      const { migrations: migrationsToRollback, blockers } = await this.planRollback(options)
+
+      // If there are blockers and not forcing, report them
+      if (blockers.length > 0 && !force) {
+        return {
+          success: false,
+          fromVersion: startVersion,
+          toVersion: startVersion,
+          durationMs: 0,
+          results: [],
+          rolledBackCount: 0,
+          skippedCount: blockers.length,
+          isDryRun: dryRun,
+          blockedBy: blockers,
+        }
+      }
+
+      await this.emitRollbackEvent({
+        type: 'batch_rollback_started',
+        options,
+        metadata: {
+          count: migrationsToRollback.length,
+          versions: migrationsToRollback.map((m) => m.version),
+        },
+      })
+
+      const results: RollbackResult[] = []
+      let rolledBackCount = 0
+      let skippedCount = 0
+      const rollbackId = generateRollbackId()
+
+      for (let i = 0; i < migrationsToRollback.length; i++) {
+        const migration = migrationsToRollback[i]
+        if (!migration) continue
+
+        const record = schemaVersion.migrations.find((m) => m.id === migration.id)
+
+        // Emit progress
+        onProgress?.({
+          migration,
+          index: i,
+          total: migrationsToRollback.length,
+          phase: 'starting',
+          isDryRun: dryRun,
+        })
+
+        // Check if migration can be rolled back
+        if (!migration.down) {
+          const result: RollbackResult = {
+            success: false,
+            id: migration.id,
+            version: migration.version,
+            executionTimeMs: 0,
+            skipped: true,
+            skipReason: 'no_down_sql',
+          }
+          results.push(result)
+          skippedCount++
+
+          onProgress?.({
+            migration,
+            index: i,
+            total: migrationsToRollback.length,
+            phase: 'skipped',
+            isDryRun: dryRun,
+          })
+
+          await this.emitRollbackEvent({
+            type: 'rollback_skipped',
+            migration,
+            result,
+          })
+
+          if (!force) {
+            // Stop on non-reversible migration unless forcing
+            break
+          }
+          continue
+        }
+
+        if (!this.isReversible(migration) && !force) {
+          const result: RollbackResult = {
+            success: false,
+            id: migration.id,
+            version: migration.version,
+            executionTimeMs: 0,
+            skipped: true,
+            skipReason: 'non_reversible',
+          }
+          results.push(result)
+          skippedCount++
+
+          onProgress?.({
+            migration,
+            index: i,
+            total: migrationsToRollback.length,
+            phase: 'skipped',
+            isDryRun: dryRun,
+          })
+
+          await this.emitRollbackEvent({
+            type: 'rollback_skipped',
+            migration,
+            result,
+          })
+
+          break
+        }
+
+        // Dry run - just record what would happen
+        if (dryRun) {
+          const result: RollbackResult = {
+            success: true,
+            id: migration.id,
+            version: migration.version,
+            executionTimeMs: 0,
+            isDryRun: true,
+          }
+          results.push(result)
+          rolledBackCount++
+
+          onProgress?.({
+            migration,
+            index: i,
+            total: migrationsToRollback.length,
+            phase: 'completed',
+            durationMs: 0,
+            isDryRun: true,
+          })
+
+          continue
+        }
+
+        // Execute the rollback
+        const migrationStartTime = performance.now()
+
+        onProgress?.({
+          migration,
+          index: i,
+          total: migrationsToRollback.length,
+          phase: 'executing',
+          isDryRun: false,
+        })
+
+        try {
+          await this.executor.query('BEGIN')
+          await this.executor.query(migration.down)
+          await this.executor.query(
+            `UPDATE ${this.getTableName()}
+             SET status = 'rolled_back', applied_at = CURRENT_TIMESTAMP
+             WHERE id = $1`,
+            [migration.id]
+          )
+          await this.executor.query('COMMIT')
+
+          const executionTimeMs = Math.round(performance.now() - migrationStartTime)
+
+          // Record in history
+          await this.recordRollbackHistory(
+            rollbackId,
+            migration,
+            record?.status ?? 'applied',
+            executionTimeMs
+          )
+
+          const result: RollbackResult = {
+            success: true,
+            id: migration.id,
+            version: migration.version,
+            executionTimeMs,
+          }
+          results.push(result)
+          rolledBackCount++
+
+          onProgress?.({
+            migration,
+            index: i,
+            total: migrationsToRollback.length,
+            phase: 'completed',
+            durationMs: executionTimeMs,
+            isDryRun: false,
+          })
+
+          await this.emitEvent({
+            type: 'migration_rolled_back',
+            migration,
+          })
+
+          await this.emitRollbackEvent({
+            type: 'rollback_completed',
+            migration,
+            result,
+          })
+
+          this.log(`Rolled back migration ${migration.id} in ${executionTimeMs}ms`)
+        } catch (error) {
+          try {
+            await this.executor.query('ROLLBACK')
+          } catch {
+            // Ignore rollback errors
+          }
+
+          const executionTimeMs = Math.round(performance.now() - migrationStartTime)
+          const errorMessage = error instanceof Error ? error.message : String(error)
+
+          const result: RollbackResult = {
+            success: false,
+            id: migration.id,
+            version: migration.version,
+            executionTimeMs,
+            error: errorMessage,
+          }
+          results.push(result)
+
+          onProgress?.({
+            migration,
+            index: i,
+            total: migrationsToRollback.length,
+            phase: 'failed',
+            durationMs: executionTimeMs,
+            error: errorMessage,
+            isDryRun: false,
+          })
+
+          await this.emitRollbackEvent({
+            type: 'rollback_failed',
+            migration,
+            result,
+            error: error instanceof Error ? error : new Error(errorMessage),
+          })
+
+          this.log(`Rollback failed for ${migration.id}:`, errorMessage)
+
+          // Stop on failure
+          break
+        }
+      }
+
+      const durationMs = Math.round(performance.now() - startTime)
+      const endVersion = dryRun
+        ? toVersion
+        : (await this.getSchemaVersion()).currentVersion
+
+      const success = results.every((r) => r.success || r.skipped)
+
+      const batchResult: BatchRollbackResult = {
+        success,
+        fromVersion: startVersion,
+        toVersion: endVersion,
+        durationMs,
+        results,
+        rolledBackCount,
+        skippedCount,
+        isDryRun: dryRun,
+        ...(blockers.length > 0 && { blockedBy: blockers }),
+      }
+
+      await this.emitRollbackEvent({
+        type: success ? 'batch_rollback_completed' : 'batch_rollback_failed',
+        batchResult,
+        options,
+      })
+
+      return batchResult
+    } finally {
+      await this.releaseLock()
+    }
+  }
+
+  /**
+   * Rollback to a specific version (legacy API)
+   *
+   * @deprecated Use rollback() instead for more options
+   */
+  async rollbackToVersion(targetVersion: number): Promise<BatchMigrationResult> {
+    const result = await this.rollback({ toVersion: targetVersion })
+
+    // Convert BatchRollbackResult to BatchMigrationResult for backwards compatibility
+    return {
+      success: result.success,
+      fromVersion: result.fromVersion,
+      toVersion: result.toVersion,
+      durationMs: result.durationMs,
+      results: result.results.map((r) => ({
+        success: r.success,
+        id: r.id,
+        executionTimeMs: r.executionTimeMs,
+        error: r.error,
+        skipped: r.skipped,
+      })),
+      migrationsRun: result.rolledBackCount,
+      migrationsSkipped: result.skippedCount,
+    }
+  }
+
+  /**
+   * Reset all migrations
+   *
+   * Drops the migrations table and all tracked migrations.
+   * USE WITH CAUTION - this doesn't undo the schema changes!
+   */
+  async reset(): Promise<void> {
+    this.log('Resetting migrations table')
+    await this.executor.query(`DROP TABLE IF EXISTS ${this.getTableName()} CASCADE`)
+    this.initialized = false
+  }
+
+  /**
+   * Check if the runner has been initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized
+  }
+
+  /**
+   * Get the registry
+   */
+  getRegistry(): MigrationRegistry {
+    return this.registry
+  }
+}
+
+/**
+ * Create a migration runner
+ *
+ * @example
+ * ```typescript
+ * const runner = createMigrationRunner(pglite, registry, {
+ *   debug: true,
+ *   onProgress: (event) => console.log(event),
+ * })
+ *
+ * await runner.migrate()
+ * ```
+ */
+export function createMigrationRunner(
+  executor: QueryExecutor,
+  registry: MigrationRegistry,
+  config: MigrationRunnerConfig = {}
+): MigrationRunner {
+  return new MigrationRunner(executor, registry, config)
+}