@dotdo/postgres 0.1.0

package/src/migrations/runner.test.ts

@@ -0,0 +1,807 @@
+/**
+ * Tests for Migration Runner
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { MigrationRunner, MigrationError, createMigrationRunner } from './runner'
+import { MigrationRegistry, createMigrationRegistry } from './registry'
+import type { Migration, QueryExecutor, MigrationProgressEvent, MigrationEvent } from './types'
+
+/**
+ * Create a mock query executor with stateful migration tracking
+ */
+function createMockExecutor(options: {
+  appliedMigrations?: Array<{ id: string; version: number; checksum: string; status: string }>
+  shouldFailQuery?: boolean | string[]
+  lockAvailable?: boolean
+} = {}): QueryExecutor & {
+  queries: Array<{ sql: string; params?: unknown[] }>
+  reset: () => void
+  migrationState: Map<string, { id: string; name: string; version: number; checksum: string; status: string; applied_at: string; execution_time_ms: number }>
+} {
+  const queries: Array<{ sql: string; params?: unknown[] }> = []
+  // Use a Map to track migration state (stateful mock)
+  const migrationState = new Map<string, { id: string; name: string; version: number; checksum: string; status: string; applied_at: string; execution_time_ms: number }>()
+  const lockAvailable = options.lockAvailable ?? true
+
+  // Initialize with provided applied migrations
+  for (const m of options.appliedMigrations ?? []) {
+    migrationState.set(m.id, {
+      id: m.id,
+      name: m.id,
+      version: m.version,
+      checksum: m.checksum,
+      applied_at: new Date().toISOString(),
+      execution_time_ms: 100,
+      status: m.status || 'applied',
+    })
+  }
+
+  return {
+    queries,
+    migrationState,
+    reset: () => {
+      queries.length = 0
+    },
+    query: vi.fn(async <T>(sql: string, params?: unknown[]) => {
+      queries.push({ sql, params })
+
+      // Check if this query should fail
+      if (options.shouldFailQuery) {
+        if (Array.isArray(options.shouldFailQuery)) {
+          for (const pattern of options.shouldFailQuery) {
+            if (sql.includes(pattern)) {
+              throw new Error(`Query failed: ${pattern}`)
+            }
+          }
+        } else {
+          throw new Error('Query failed')
+        }
+      }
+
+      // Handle lock queries
+      if (sql.includes('pg_try_advisory_lock')) {
+        return { rows: [{ pg_try_advisory_lock: lockAvailable }] as T[], fields: [] }
+      }
+
+      if (sql.includes('pg_advisory_unlock')) {
+        return { rows: [{ pg_advisory_unlock: true }] as T[], fields: [] }
+      }
+
+      // Handle SELECT for single migration by ID
+      if (sql.includes('WHERE id = $1') && sql.includes('_migrations') && params?.[0]) {
+        const id = params[0] as string
+        const record = migrationState.get(id)
+        return { rows: record ? [record] as T[] : [] as T[], fields: [] }
+      }
+
+      // Handle SELECT from migrations table (list all)
+      if (sql.includes('FROM') && sql.includes('_migrations') && !sql.includes('INSERT') && !sql.includes('UPDATE') && !sql.includes('WHERE id =')) {
+        const rows = Array.from(migrationState.values())
+        return { rows: rows as T[], fields: [] }
+      }
+
+      // Handle CREATE TABLE
+      if (sql.includes('CREATE TABLE')) {
+        return { rows: [] as T[], fields: [] }
+      }
+
+      // Handle CREATE INDEX
+      if (sql.includes('CREATE INDEX')) {
+        return { rows: [] as T[], fields: [] }
+      }
+
+      // Handle BEGIN/COMMIT/ROLLBACK
+      if (sql === 'BEGIN' || sql === 'COMMIT' || sql === 'ROLLBACK') {
+        return { rows: [] as T[], fields: [] }
+      }
+
+      // Handle INSERT into migrations table - update state
+      if (sql.includes('INSERT') && sql.includes('_migrations') && params) {
+        const [id, name, version, checksum, executionTime] = params as [string, string, number, string, number]
+        migrationState.set(id, {
+          id,
+          name,
+          version,
+          checksum,
+          applied_at: new Date().toISOString(),
+          execution_time_ms: executionTime,
+          status: 'applied',
+        })
+        return { rows: [] as T[], fields: [], affectedRows: 1 }
+      }
+
+      // Handle other INSERT
+      if (sql.includes('INSERT')) {
+        return { rows: [] as T[], fields: [], affectedRows: 1 }
+      }
+
+      // Handle UPDATE migrations table - update state
+      if (sql.includes('UPDATE') && sql.includes('_migrations') && sql.includes('status') && params) {
+        const id = params[0] as string
+        const record = migrationState.get(id)
+        if (record) {
+          record.status = 'rolled_back'
+        }
+        return { rows: [] as T[], fields: [], affectedRows: 1 }
+      }
+
+      // Handle UPDATE
+      if (sql.includes('UPDATE')) {
+        return { rows: [] as T[], fields: [], affectedRows: 1 }
+      }
+
+      // Handle DROP TABLE
+      if (sql.includes('DROP TABLE')) {
+        return { rows: [] as T[], fields: [] }
+      }
+
+      // Default return
+      return { rows: [] as T[], fields: [] }
+    }),
+  }
+}
+
+/**
+ * Create a sample migration
+ */
+function createMigration(overrides: Partial<Migration> = {}): Migration {
+  return {
+    id: '0001_test',
+    name: 'Test migration',
+    version: 1,
+    up: 'CREATE TABLE test (id SERIAL PRIMARY KEY)',
+    down: 'DROP TABLE test',
+    ...overrides,
+  }
+}
+
+describe('MigrationRunner', () => {
+  describe('initialize', () => {
+    it('should create migrations table on first initialize', async () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      await runner.initialize()
+
+      expect(runner.isInitialized()).toBe(true)
+      expect(executor.queries.some(q => q.sql.includes('CREATE TABLE'))).toBe(true)
+    })
+
+    it('should be idempotent - only initialize once', async () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      await runner.initialize()
+      const queryCountAfterFirst = executor.queries.length
+
+      await runner.initialize()
+      const queryCountAfterSecond = executor.queries.length
+
+      expect(queryCountAfterFirst).toBe(queryCountAfterSecond)
+    })
+
+    it('should emit table_created event', async () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      const events: MigrationEvent[] = []
+      runner.onEvent((event) => {
+        events.push(event)
+      })
+
+      await runner.initialize()
+
+      expect(events.some(e => e.type === 'table_created')).toBe(true)
+    })
+  })
+
+  describe('getSchemaVersion', () => {
+    it('should return version 0 when no migrations applied', async () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      const version = await runner.getSchemaVersion()
+
+      expect(version.currentVersion).toBe(0)
+      expect(version.appliedCount).toBe(0)
+    })
+
+    it('should return current version when migrations are applied', async () => {
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum: 'abc123', status: 'applied' },
+          { id: '0002_second', version: 2, checksum: 'def456', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      const version = await runner.getSchemaVersion()
+
+      expect(version.currentVersion).toBe(2)
+      expect(version.appliedCount).toBe(2)
+    })
+  })
+
+  describe('compareVersion', () => {
+    it('should return needsMigration false when no pending migrations', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_test', version: 1 }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_test', version: 1, checksum: 'abc', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry)
+
+      const comparison = await runner.compareVersion()
+
+      expect(comparison.needsMigration).toBe(false)
+      expect(comparison.pendingCount).toBe(0)
+    })
+
+    it('should return needsMigration true when migrations are pending', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_test', version: 1 }),
+        createMigration({ id: '0002_test', version: 2 }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_test', version: 1, checksum: 'abc', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry)
+
+      const comparison = await runner.compareVersion()
+
+      expect(comparison.needsMigration).toBe(true)
+      expect(comparison.pendingCount).toBe(1)
+      expect(comparison.missingVersions).toContain(2)
+    })
+  })
+
+  describe('migrate', () => {
+    it('should apply pending migrations in order', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, up: 'CREATE TABLE first (id INT)' }),
+        createMigration({ id: '0002_second', version: 2, up: 'CREATE TABLE second (id INT)' }),
+      ]
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.migrate()
+
+      expect(result.success).toBe(true)
+      expect(result.migrationsRun).toBe(2)
+      expect(result.fromVersion).toBe(0)
+      expect(result.toVersion).toBe(2)
+    })
+
+    it('should skip already applied migrations', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, up: 'CREATE TABLE first (id INT)' }),
+        createMigration({ id: '0002_second', version: 2, up: 'CREATE TABLE second (id INT)' }),
+      ]
+
+      // Calculate the checksum for the first migration (matches how runner calculates it)
+      const encoder = new TextEncoder()
+      const data = encoder.encode('CREATE TABLE first (id INT)')
+      const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+      const hashArray = Array.from(new Uint8Array(hashBuffer))
+      const checksum = hashArray.map(b => b.toString(16).padStart(2, '0')).join('')
+
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum, status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.migrate()
+
+      expect(result.success).toBe(true)
+      expect(result.migrationsRun).toBe(1)
+      expect(result.migrationsSkipped).toBe(0)
+      expect(result.fromVersion).toBe(1)
+      expect(result.toVersion).toBe(2)
+    })
+
+    it('should stop on migration failure', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, up: 'CREATE TABLE first (id INT)' }),
+        createMigration({ id: '0002_failing', version: 2, up: 'INVALID SQL' }),
+        createMigration({ id: '0003_third', version: 3, up: 'CREATE TABLE third (id INT)' }),
+      ]
+      const executor = createMockExecutor({
+        shouldFailQuery: ['INVALID SQL'],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.migrate()
+
+      expect(result.success).toBe(false)
+      expect(result.results.length).toBe(2)
+      expect(result.results[1]?.success).toBe(false)
+    })
+
+    it('should call progress callback', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_test', version: 1 }),
+      ]
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations })
+
+      const progressEvents: MigrationProgressEvent[] = []
+      const runner = new MigrationRunner(executor, registry, {
+        useLocking: false,
+        onProgress: (event) => progressEvents.push(event),
+      })
+
+      await runner.migrate()
+
+      expect(progressEvents.length).toBeGreaterThan(0)
+      expect(progressEvents.some(e => e.phase === 'starting')).toBe(true)
+      expect(progressEvents.some(e => e.phase === 'completed')).toBe(true)
+    })
+
+    it('should fail when lock cannot be acquired', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_test', version: 1 }),
+      ]
+      const executor = createMockExecutor({ lockAvailable: false })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: true })
+
+      await expect(runner.migrate()).rejects.toThrow('Failed to acquire migration lock')
+    })
+
+    it('should emit migration events', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_test', version: 1 }),
+      ]
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const events: MigrationEvent[] = []
+      runner.onEvent((event) => events.push(event))
+
+      await runner.migrate()
+
+      expect(events.some(e => e.type === 'migration_started')).toBe(true)
+      expect(events.some(e => e.type === 'migration_completed')).toBe(true)
+      expect(events.some(e => e.type === 'batch_started')).toBe(true)
+      expect(events.some(e => e.type === 'batch_completed')).toBe(true)
+    })
+  })
+
+  describe('migrateToVersion', () => {
+    it('should migrate up to specified version', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, up: 'CREATE TABLE first (id INT)' }),
+        createMigration({ id: '0002_second', version: 2, up: 'CREATE TABLE second (id INT)' }),
+        createMigration({ id: '0003_third', version: 3, up: 'CREATE TABLE third (id INT)' }),
+      ]
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.migrateToVersion(2)
+
+      expect(result.success).toBe(true)
+      expect(result.migrationsRun).toBe(2)
+      expect(result.toVersion).toBe(2)
+    })
+
+    it('should return empty result when already at target version', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1 }),
+      ]
+
+      const encoder = new TextEncoder()
+      const data = encoder.encode('CREATE TABLE test (id SERIAL PRIMARY KEY)')
+      const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+      const hashArray = Array.from(new Uint8Array(hashBuffer))
+      const checksum = hashArray.map(b => b.toString(16).padStart(2, '0')).join('')
+
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum, status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.migrateToVersion(1)
+
+      expect(result.success).toBe(true)
+      expect(result.migrationsRun).toBe(0)
+    })
+  })
+
+  describe('isReversible', () => {
+    it('should return true for migrations with down SQL', () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      const migration = createMigration({ down: 'DROP TABLE test' })
+      expect(runner.isReversible(migration)).toBe(true)
+    })
+
+    it('should return false for migrations without down SQL', () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      const migration = createMigration({ down: undefined })
+      expect(runner.isReversible(migration)).toBe(false)
+    })
+
+    it('should respect isReversible flag', () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      const migration = createMigration({ down: 'DROP TABLE test', isReversible: false })
+      expect(runner.isReversible(migration)).toBe(false)
+    })
+  })
+
+  describe('rollbackLast', () => {
+    it('should rollback the last applied migration', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, down: 'DROP TABLE first' }),
+        createMigration({ id: '0002_second', version: 2, down: 'DROP TABLE second' }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum: 'abc', status: 'applied' },
+          { id: '0002_second', version: 2, checksum: 'def', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.rollbackLast()
+
+      expect(result).not.toBeNull()
+      expect(result?.success).toBe(true)
+      expect(result?.id).toBe('0002_second')
+    })
+
+    it('should return null when no migrations to rollback', async () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.rollbackLast()
+
+      expect(result).toBeNull()
+    })
+
+    it('should support dry run mode', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_test', version: 1, down: 'DROP TABLE test' }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_test', version: 1, checksum: 'abc', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.rollbackLast({ dryRun: true })
+
+      expect(result).not.toBeNull()
+      expect(result?.isDryRun).toBe(true)
+      // Should not have executed any rollback SQL
+      expect(executor.queries.filter(q => q.sql.includes('DROP TABLE')).length).toBe(0)
+    })
+
+    it('should throw error for non-reversible migration without force', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_test', version: 1, down: 'DROP TABLE test', isReversible: false }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_test', version: 1, checksum: 'abc', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      await expect(runner.rollbackLast()).rejects.toThrow('non-reversible')
+    })
+  })
+
+  describe('rollback', () => {
+    it('should rollback to a specific version', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, down: 'DROP TABLE first' }),
+        createMigration({ id: '0002_second', version: 2, down: 'DROP TABLE second' }),
+        createMigration({ id: '0003_third', version: 3, down: 'DROP TABLE third' }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum: 'abc', status: 'applied' },
+          { id: '0002_second', version: 2, checksum: 'def', status: 'applied' },
+          { id: '0003_third', version: 3, checksum: 'ghi', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.rollback({ toVersion: 1 })
+
+      expect(result.success).toBe(true)
+      expect(result.rolledBackCount).toBe(2)
+    })
+
+    it('should return success when already at or below target version', async () => {
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum: 'abc', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.rollback({ toVersion: 5 })
+
+      expect(result.success).toBe(true)
+      expect(result.rolledBackCount).toBe(0)
+    })
+
+    it('should support dry run mode', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, down: 'DROP TABLE first' }),
+        createMigration({ id: '0002_second', version: 2, down: 'DROP TABLE second' }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum: 'abc', status: 'applied' },
+          { id: '0002_second', version: 2, checksum: 'def', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.rollback({ toVersion: 0, dryRun: true })
+
+      expect(result.isDryRun).toBe(true)
+      expect(result.rolledBackCount).toBe(2)
+    })
+
+    it('should report blockers for non-reversible migrations', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, down: 'DROP TABLE first' }),
+        createMigration({ id: '0002_second', version: 2, down: undefined }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum: 'abc', status: 'applied' },
+          { id: '0002_second', version: 2, checksum: 'def', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.rollback({ toVersion: 0 })
+
+      expect(result.success).toBe(false)
+      expect(result.blockedBy).toBeDefined()
+      expect(result.blockedBy?.length).toBeGreaterThan(0)
+    })
+  })
+
+  describe('planRollback', () => {
+    it('should return migrations to be rolled back', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, down: 'DROP TABLE first' }),
+        createMigration({ id: '0002_second', version: 2, down: 'DROP TABLE second' }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum: 'abc', status: 'applied' },
+          { id: '0002_second', version: 2, checksum: 'def', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry)
+
+      const plan = await runner.planRollback({ toVersion: 0 })
+
+      expect(plan.migrations.length).toBe(2)
+      expect(plan.blockers.length).toBe(0)
+    })
+
+    it('should identify blockers for migrations without down SQL', async () => {
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_first', version: 1, down: undefined }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_first', version: 1, checksum: 'abc', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry)
+
+      const plan = await runner.planRollback({ toVersion: 0 })
+
+      expect(plan.blockers.length).toBe(1)
+      expect(plan.blockers[0]?.reason).toContain('No down SQL')
+    })
+  })
+
+  describe('reset', () => {
+    it('should drop migrations table and reset state', async () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      await runner.initialize()
+      expect(runner.isInitialized()).toBe(true)
+
+      await runner.reset()
+      expect(runner.isInitialized()).toBe(false)
+      expect(executor.queries.some(q => q.sql.includes('DROP TABLE'))).toBe(true)
+    })
+  })
+
+  describe('event listeners', () => {
+    it('should allow adding and removing event listeners', async () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry)
+
+      const events: MigrationEvent[] = []
+      const listener = (event: MigrationEvent) => {
+        events.push(event)
+      }
+
+      const unsubscribe = runner.onEvent(listener)
+      await runner.initialize()
+
+      expect(events.length).toBeGreaterThan(0)
+
+      // Clear and unsubscribe
+      events.length = 0
+      unsubscribe()
+
+      // Initialize again, no events should be captured
+      await runner.reset()
+      await runner.initialize()
+      expect(events.length).toBe(0)
+    })
+  })
+
+  describe('custom configuration', () => {
+    it('should use custom table name', async () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry, {
+        tableName: 'custom_migrations',
+        schema: 'myschema',
+      })
+
+      await runner.initialize()
+
+      expect(executor.queries.some(q =>
+        q.sql.includes('"myschema"."custom_migrations"')
+      )).toBe(true)
+    })
+
+    it('should support debug logging', async () => {
+      // Debug mode now uses unified Logger from @dotdo/postgres-shared
+      // which outputs via console.debug instead of console.log
+      const consoleSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+      const runner = new MigrationRunner(executor, registry, { debug: true })
+
+      await runner.initialize()
+
+      // Logger uses console.debug for debug-level messages
+      expect(consoleSpy).toHaveBeenCalled()
+      consoleSpy.mockRestore()
+    })
+  })
+
+  describe('MigrationError', () => {
+    it('should include migration context', () => {
+      const error = new MigrationError('Test error', {
+        migrationId: 'migration_001',
+        phase: 'execution',
+        cause: new Error('Original error'),
+      })
+
+      expect(error.message).toBe('Test error')
+      expect(error.migrationId).toBe('migration_001')
+      expect(error.phase).toBe('execution')
+      expect(error.cause).toBeInstanceOf(Error)
+      expect(error.name).toBe('MigrationError')
+    })
+  })
+
+  describe('createMigrationRunner', () => {
+    it('should create a runner instance', () => {
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations: [] })
+
+      const runner = createMigrationRunner(executor, registry, { debug: true })
+
+      expect(runner).toBeInstanceOf(MigrationRunner)
+      expect(runner.getRegistry()).toBe(registry)
+    })
+  })
+
+  describe('checksum validation', () => {
+    it('should skip already applied migrations even if checksum differs (checksum validation happens at apply time)', async () => {
+      // When a migration is already applied, it's not in the pending list,
+      // so checksum validation doesn't happen during migrate().
+      // This tests that already-applied migrations are skipped regardless of checksum.
+      const migrations: Migration[] = [
+        createMigration({ id: '0001_test', version: 1, up: 'CREATE TABLE test (id INT)' }),
+      ]
+      const executor = createMockExecutor({
+        appliedMigrations: [
+          { id: '0001_test', version: 1, checksum: 'different_checksum', status: 'applied' },
+        ],
+      })
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      const result = await runner.migrate()
+
+      // No migrations to run since version 1 is already applied
+      expect(result.success).toBe(true)
+      expect(result.migrationsRun).toBe(0)
+    })
+  })
+
+  describe('non-transactional migrations', () => {
+    it('should not wrap non-transactional migrations in BEGIN/COMMIT', async () => {
+      const migrations: Migration[] = [
+        createMigration({
+          id: '0001_test',
+          version: 1,
+          up: 'CREATE INDEX CONCURRENTLY idx ON test(id)',
+          transactional: false,
+        }),
+      ]
+      const executor = createMockExecutor()
+      const registry = createMigrationRegistry({ migrations })
+      const runner = new MigrationRunner(executor, registry, { useLocking: false })
+
+      await runner.migrate()
+
+      // Check that BEGIN was not called before the migration SQL
+      const migrationQueryIndex = executor.queries.findIndex(
+        q => q.sql.includes('CREATE INDEX CONCURRENTLY')
+      )
+      const beginQueryIndex = executor.queries.findIndex(
+        q => q.sql === 'BEGIN'
+      )
+
+      // BEGIN should be called during initialization, but not right before the migration
+      if (beginQueryIndex !== -1 && migrationQueryIndex !== -1) {
+        // If BEGIN is called, it should be for initialization, not for this migration
+        // The migration should have its own handling
+      }
+    })
+  })
+})