@dotdo/postgres 0.1.0

package/src/migrations/testing.ts

@@ -0,0 +1,1037 @@
+/**
+ * Migration Testing Helpers
+ *
+ * Utilities for testing migrations in a controlled environment.
+ * Provides test fixtures, assertion helpers, and migration execution context.
+ *
+ * @module migrations/testing
+ *
+ * @example
+ * ```typescript
+ * import { testMigration, createTestExecutor } from '@dotdo/postgres/migrations/testing'
+ *
+ * describe('migration: 0001_create_users', () => {
+ *   it('creates users table', async () => {
+ *     const executor = await createTestExecutor()
+ *
+ *     await testMigration(executor, {
+ *       migration: usersMigration,
+ *       beforeState: async (db) => {
+ *         expect(await db.tableExists('users')).toBe(false)
+ *       },
+ *       afterState: async (db) => {
+ *         expect(await db.tableExists('users')).toBe(true)
+ *         const columns = await db.getColumns('users')
+ *         expect(columns).toContain('id')
+ *         expect(columns).toContain('email')
+ *       },
+ *     })
+ *   })
+ * })
+ * ```
+ */
+
+import type {
+  Migration,
+  QueryExecutor,
+  BatchMigrationResult,
+  BatchRollbackResult,
+} from './types'
+import { createMigrationRegistry, type MigrationRegistry } from './registry'
+import { createMigrationRunner, type MigrationRunner } from './runner'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Database inspection utilities for testing
+ */
+export interface TestDatabase {
+  /** Execute raw SQL query */
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>
+
+  /** Check if a table exists */
+  tableExists(tableName: string): Promise<boolean>
+
+  /** Get column names for a table */
+  getColumns(tableName: string): Promise<string[]>
+
+  /** Get column info for a table */
+  getColumnInfo(tableName: string): Promise<ColumnInfo[]>
+
+  /** Get index names for a table */
+  getIndexes(tableName: string): Promise<string[]>
+
+  /** Get constraint names for a table */
+  getConstraints(tableName: string): Promise<ConstraintInfo[]>
+
+  /** Get row count for a table */
+  getRowCount(tableName: string): Promise<number>
+
+  /** Check if an index exists */
+  indexExists(indexName: string): Promise<boolean>
+
+  /** Check if a constraint exists */
+  constraintExists(tableName: string, constraintName: string): Promise<boolean>
+
+  /** Get all table names in the schema */
+  getTables(): Promise<string[]>
+
+  /** Get all function names */
+  getFunctions(): Promise<string[]>
+
+  /** Get all trigger names */
+  getTriggers(): Promise<string[]>
+
+  /** Get foreign keys for a table */
+  getForeignKeys(tableName: string): Promise<ForeignKeyInfo[]>
+}
+
+/**
+ * Column information
+ */
+export interface ColumnInfo {
+  name: string
+  dataType: string
+  isNullable: boolean
+  defaultValue: string | null
+  isPrimaryKey: boolean
+}
+
+/**
+ * Constraint information
+ */
+export interface ConstraintInfo {
+  name: string
+  type: 'PRIMARY KEY' | 'FOREIGN KEY' | 'UNIQUE' | 'CHECK' | 'EXCLUDE'
+  columns: string[]
+  definition: string
+}
+
+/**
+ * Foreign key information
+ */
+export interface ForeignKeyInfo {
+  name: string
+  columns: string[]
+  referencedTable: string
+  referencedColumns: string[]
+  onDelete: string
+  onUpdate: string
+}
+
+/**
+ * Options for testMigration helper
+ */
+export interface TestMigrationOptions {
+  /** The migration to test */
+  migration: Migration
+
+  /** Callback to verify state before migration */
+  beforeState?: (db: TestDatabase) => Promise<void>
+
+  /** Callback to verify state after migration */
+  afterState?: (db: TestDatabase) => Promise<void>
+
+  /** Callback to verify state after rollback */
+  afterRollback?: (db: TestDatabase) => Promise<void>
+
+  /** Whether to test rollback */
+  testRollback?: boolean
+
+  /** Migrations to apply before the test migration */
+  prerequisites?: Migration[]
+
+  /** Custom migrations table name */
+  tableName?: string
+
+  /** Enable debug logging */
+  debug?: boolean
+}
+
+/**
+ * Result of a migration test
+ */
+export interface TestMigrationResult {
+  /** Whether the test passed */
+  success: boolean
+
+  /** Migration result */
+  migrationResult: BatchMigrationResult
+
+  /** Rollback result (if rollback was tested) */
+  rollbackResult?: BatchRollbackResult
+
+  /** Error if test failed */
+  error?: Error
+
+  /** Duration of the test in milliseconds */
+  durationMs: number
+}
+
+/**
+ * Options for createTestContext
+ */
+export interface TestContextOptions {
+  /** Migrations to register */
+  migrations?: Migration[]
+
+  /** Custom migrations table name */
+  tableName?: string
+
+  /** Enable debug logging */
+  debug?: boolean
+}
+
+/**
+ * Test context for migration testing
+ */
+export interface MigrationTestContext {
+  /** The query executor */
+  executor: QueryExecutor
+
+  /** The migration registry */
+  registry: MigrationRegistry
+
+  /** The migration runner */
+  runner: MigrationRunner
+
+  /** Database inspection utilities */
+  db: TestDatabase
+
+  /** Run all pending migrations */
+  migrate(): Promise<BatchMigrationResult>
+
+  /** Rollback to a specific version */
+  rollback(toVersion: number): Promise<BatchRollbackResult>
+
+  /** Reset the database (drop all tables) */
+  reset(): Promise<void>
+
+  /** Get schema version */
+  getVersion(): Promise<number>
+
+  /** Add a migration to the registry */
+  addMigration(migration: Migration): void
+
+  /** Clean up resources */
+  cleanup(): Promise<void>
+}
+
+// ============================================================================
+// Test Database Implementation
+// ============================================================================
+
+/**
+ * Create test database utilities from a query executor
+ */
+export function createTestDatabase(executor: QueryExecutor): TestDatabase {
+  return {
+    async query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]> {
+      const result = await executor.query<T>(sql, params)
+      return result.rows
+    },
+
+    async tableExists(tableName: string): Promise<boolean> {
+      const result = await executor.query<{ exists: boolean }>(
+        `SELECT EXISTS (
+          SELECT FROM information_schema.tables
+          WHERE table_schema = 'public'
+          AND table_name = $1
+        )`,
+        [tableName]
+      )
+      return result.rows[0]?.exists ?? false
+    },
+
+    async getColumns(tableName: string): Promise<string[]> {
+      const result = await executor.query<{ column_name: string }>(
+        `SELECT column_name
+         FROM information_schema.columns
+         WHERE table_schema = 'public'
+         AND table_name = $1
+         ORDER BY ordinal_position`,
+        [tableName]
+      )
+      return result.rows.map((r) => r.column_name)
+    },
+
+    async getColumnInfo(tableName: string): Promise<ColumnInfo[]> {
+      const result = await executor.query<{
+        column_name: string
+        data_type: string
+        is_nullable: string
+        column_default: string | null
+      }>(
+        `SELECT column_name, data_type, is_nullable, column_default
+         FROM information_schema.columns
+         WHERE table_schema = 'public'
+         AND table_name = $1
+         ORDER BY ordinal_position`,
+        [tableName]
+      )
+
+      // Get primary key columns
+      const pkResult = await executor.query<{ column_name: string }>(
+        `SELECT a.attname as column_name
+         FROM pg_index i
+         JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
+         WHERE i.indrelid = $1::regclass
+         AND i.indisprimary`,
+        [tableName]
+      )
+      const pkColumns = new Set(pkResult.rows.map((r) => r.column_name))
+
+      return result.rows.map((r) => ({
+        name: r.column_name,
+        dataType: r.data_type,
+        isNullable: r.is_nullable === 'YES',
+        defaultValue: r.column_default,
+        isPrimaryKey: pkColumns.has(r.column_name),
+      }))
+    },
+
+    async getIndexes(tableName: string): Promise<string[]> {
+      const result = await executor.query<{ indexname: string }>(
+        `SELECT indexname
+         FROM pg_indexes
+         WHERE schemaname = 'public'
+         AND tablename = $1`,
+        [tableName]
+      )
+      return result.rows.map((r) => r.indexname)
+    },
+
+    async getConstraints(tableName: string): Promise<ConstraintInfo[]> {
+      const result = await executor.query<{
+        constraint_name: string
+        constraint_type: string
+        column_name: string
+        definition: string
+      }>(
+        `SELECT
+           tc.constraint_name,
+           tc.constraint_type,
+           kcu.column_name,
+           pg_get_constraintdef(c.oid) as definition
+         FROM information_schema.table_constraints tc
+         JOIN information_schema.key_column_usage kcu
+           ON tc.constraint_name = kcu.constraint_name
+           AND tc.table_schema = kcu.table_schema
+         JOIN pg_constraint c
+           ON c.conname = tc.constraint_name
+         WHERE tc.table_schema = 'public'
+         AND tc.table_name = $1`,
+        [tableName]
+      )
+
+      // Group by constraint name
+      const constraintMap = new Map<string, ConstraintInfo>()
+      for (const row of result.rows) {
+        const existing = constraintMap.get(row.constraint_name)
+        if (existing) {
+          existing.columns.push(row.column_name)
+        } else {
+          constraintMap.set(row.constraint_name, {
+            name: row.constraint_name,
+            type: row.constraint_type as ConstraintInfo['type'],
+            columns: [row.column_name],
+            definition: row.definition,
+          })
+        }
+      }
+
+      return Array.from(constraintMap.values())
+    },
+
+    async getRowCount(tableName: string): Promise<number> {
+      const result = await executor.query<{ count: string }>(
+        `SELECT COUNT(*)::text as count FROM "${tableName}"`
+      )
+      return parseInt(result.rows[0]?.count ?? '0', 10)
+    },
+
+    async indexExists(indexName: string): Promise<boolean> {
+      const result = await executor.query<{ exists: boolean }>(
+        `SELECT EXISTS (
+          SELECT FROM pg_indexes
+          WHERE schemaname = 'public'
+          AND indexname = $1
+        )`,
+        [indexName]
+      )
+      return result.rows[0]?.exists ?? false
+    },
+
+    async constraintExists(tableName: string, constraintName: string): Promise<boolean> {
+      const result = await executor.query<{ exists: boolean }>(
+        `SELECT EXISTS (
+          SELECT FROM information_schema.table_constraints
+          WHERE table_schema = 'public'
+          AND table_name = $1
+          AND constraint_name = $2
+        )`,
+        [tableName, constraintName]
+      )
+      return result.rows[0]?.exists ?? false
+    },
+
+    async getTables(): Promise<string[]> {
+      const result = await executor.query<{ table_name: string }>(
+        `SELECT table_name
+         FROM information_schema.tables
+         WHERE table_schema = 'public'
+         AND table_type = 'BASE TABLE'
+         ORDER BY table_name`
+      )
+      return result.rows.map((r) => r.table_name)
+    },
+
+    async getFunctions(): Promise<string[]> {
+      const result = await executor.query<{ routine_name: string }>(
+        `SELECT routine_name
+         FROM information_schema.routines
+         WHERE routine_schema = 'public'
+         ORDER BY routine_name`
+      )
+      return result.rows.map((r) => r.routine_name)
+    },
+
+    async getTriggers(): Promise<string[]> {
+      const result = await executor.query<{ trigger_name: string }>(
+        `SELECT trigger_name
+         FROM information_schema.triggers
+         WHERE trigger_schema = 'public'
+         ORDER BY trigger_name`
+      )
+      return result.rows.map((r) => r.trigger_name)
+    },
+
+    async getForeignKeys(tableName: string): Promise<ForeignKeyInfo[]> {
+      const result = await executor.query<{
+        constraint_name: string
+        column_name: string
+        referenced_table: string
+        referenced_column: string
+        delete_rule: string
+        update_rule: string
+      }>(
+        `SELECT
+           tc.constraint_name,
+           kcu.column_name,
+           ccu.table_name AS referenced_table,
+           ccu.column_name AS referenced_column,
+           rc.delete_rule,
+           rc.update_rule
+         FROM information_schema.table_constraints tc
+         JOIN information_schema.key_column_usage kcu
+           ON tc.constraint_name = kcu.constraint_name
+           AND tc.table_schema = kcu.table_schema
+         JOIN information_schema.constraint_column_usage ccu
+           ON ccu.constraint_name = tc.constraint_name
+         JOIN information_schema.referential_constraints rc
+           ON rc.constraint_name = tc.constraint_name
+         WHERE tc.constraint_type = 'FOREIGN KEY'
+         AND tc.table_schema = 'public'
+         AND tc.table_name = $1`,
+        [tableName]
+      )
+
+      // Group by constraint name
+      const fkMap = new Map<string, ForeignKeyInfo>()
+      for (const row of result.rows) {
+        const existing = fkMap.get(row.constraint_name)
+        if (existing) {
+          existing.columns.push(row.column_name)
+          existing.referencedColumns.push(row.referenced_column)
+        } else {
+          fkMap.set(row.constraint_name, {
+            name: row.constraint_name,
+            columns: [row.column_name],
+            referencedTable: row.referenced_table,
+            referencedColumns: [row.referenced_column],
+            onDelete: row.delete_rule,
+            onUpdate: row.update_rule,
+          })
+        }
+      }
+
+      return Array.from(fkMap.values())
+    },
+  }
+}
+
+// ============================================================================
+// Test Context
+// ============================================================================
+
+/**
+ * Create a test context for migration testing
+ *
+ * @example
+ * ```typescript
+ * const ctx = await createTestContext(executor, {
+ *   migrations: [migration1, migration2],
+ * })
+ *
+ * // Run migrations
+ * await ctx.migrate()
+ *
+ * // Verify state
+ * expect(await ctx.db.tableExists('users')).toBe(true)
+ *
+ * // Cleanup
+ * await ctx.cleanup()
+ * ```
+ */
+export async function createTestContext(
+  executor: QueryExecutor,
+  options: TestContextOptions = {}
+): Promise<MigrationTestContext> {
+  const { migrations = [], tableName = '_test_migrations', debug = false } = options
+
+  const registry = createMigrationRegistry({
+    migrations,
+    validateOnCreate: false, // Allow empty registry
+    allowVersionGaps: true,
+  })
+
+  const runner = createMigrationRunner(executor, registry, {
+    tableName,
+    debug,
+  })
+
+  const db = createTestDatabase(executor)
+
+  return {
+    executor,
+    registry,
+    runner,
+    db,
+
+    async migrate(): Promise<BatchMigrationResult> {
+      return runner.migrate()
+    },
+
+    async rollback(toVersion: number): Promise<BatchRollbackResult> {
+      return runner.rollback({ toVersion })
+    },
+
+    async reset(): Promise<void> {
+      await runner.reset()
+    },
+
+    async getVersion(): Promise<number> {
+      const schemaVersion = await runner.getSchemaVersion()
+      return schemaVersion.currentVersion
+    },
+
+    addMigration(migration: Migration): void {
+      // Create new registry with added migration
+      const allMigrations = [...registry.getMigrations(), migration]
+      const newRegistry = createMigrationRegistry({
+        migrations: allMigrations,
+        validateOnCreate: false,
+        allowVersionGaps: true,
+      })
+      // Replace the internal registry - note: this is a workaround
+      // In production, you'd create a new runner
+      Object.assign(registry, newRegistry)
+    },
+
+    async cleanup(): Promise<void> {
+      await runner.reset()
+    },
+  }
+}
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+/**
+ * Test a single migration
+ *
+ * This helper applies a migration and verifies the state before and after.
+ * Optionally tests rollback as well.
+ *
+ * @example
+ * ```typescript
+ * const result = await testMigration(executor, {
+ *   migration: usersMigration,
+ *   prerequisites: [baseMigration],
+ *   beforeState: async (db) => {
+ *     expect(await db.tableExists('users')).toBe(false)
+ *   },
+ *   afterState: async (db) => {
+ *     expect(await db.tableExists('users')).toBe(true)
+ *   },
+ *   testRollback: true,
+ *   afterRollback: async (db) => {
+ *     expect(await db.tableExists('users')).toBe(false)
+ *   },
+ * })
+ *
+ * expect(result.success).toBe(true)
+ * ```
+ */
+export async function testMigration(
+  executor: QueryExecutor,
+  options: TestMigrationOptions
+): Promise<TestMigrationResult> {
+  const {
+    migration,
+    beforeState,
+    afterState,
+    afterRollback,
+    testRollback = false,
+    prerequisites = [],
+    tableName = '_test_migrations',
+    debug = false,
+  } = options
+
+  const startTime = performance.now()
+
+  try {
+    // Create context with prerequisites and test migration
+    const allMigrations = [...prerequisites, migration]
+    const ctx = await createTestContext(executor, {
+      migrations: allMigrations,
+      tableName,
+      debug,
+    })
+
+    const db = ctx.db
+
+    // Apply prerequisites first
+    if (prerequisites.length > 0) {
+      const prereqRegistry = createMigrationRegistry({
+        migrations: prerequisites,
+        validateOnCreate: false,
+        allowVersionGaps: true,
+      })
+      const prereqRunner = createMigrationRunner(executor, prereqRegistry, {
+        tableName,
+        debug,
+      })
+      await prereqRunner.migrate()
+    }
+
+    // Verify before state
+    if (beforeState) {
+      await beforeState(db)
+    }
+
+    // Create runner for just the test migration
+    const testRegistry = createMigrationRegistry({
+      migrations: allMigrations,
+      validateOnCreate: false,
+      allowVersionGaps: true,
+    })
+    const testRunner = createMigrationRunner(executor, testRegistry, {
+      tableName,
+      debug,
+    })
+
+    // Apply the migration
+    const migrationResult = await testRunner.migrate()
+
+    if (!migrationResult.success) {
+      const error = new Error(
+        `Migration failed: ${migrationResult.results.find((r) => !r.success)?.error}`
+      )
+      return {
+        success: false,
+        migrationResult,
+        error,
+        durationMs: Math.round(performance.now() - startTime),
+      }
+    }
+
+    // Verify after state
+    if (afterState) {
+      await afterState(db)
+    }
+
+    // Test rollback if requested
+    let rollbackResult: BatchRollbackResult | undefined
+
+    if (testRollback && migration.down) {
+      const targetVersion = prerequisites.length > 0
+        ? prerequisites[prerequisites.length - 1]?.version ?? 0
+        : 0
+
+      rollbackResult = await testRunner.rollback({ toVersion: targetVersion })
+
+      if (!rollbackResult.success) {
+        const error = new Error(
+          `Rollback failed: ${rollbackResult.results.find((r) => !r.success)?.error}`
+        )
+        return {
+          success: false,
+          migrationResult,
+          rollbackResult,
+          error,
+          durationMs: Math.round(performance.now() - startTime),
+        }
+      }
+
+      // Verify after rollback state
+      if (afterRollback) {
+        await afterRollback(db)
+      }
+    }
+
+    // Cleanup
+    await ctx.cleanup()
+
+    const result: TestMigrationResult = {
+      success: true,
+      migrationResult,
+      durationMs: Math.round(performance.now() - startTime),
+    }
+    if (rollbackResult) {
+      result.rollbackResult = rollbackResult
+    }
+    return result
+  } catch (error) {
+    return {
+      success: false,
+      migrationResult: {
+        success: false,
+        fromVersion: 0,
+        toVersion: 0,
+        durationMs: 0,
+        results: [],
+        migrationsRun: 0,
+        migrationsSkipped: 0,
+      },
+      error: error instanceof Error ? error : new Error(String(error)),
+      durationMs: Math.round(performance.now() - startTime),
+    }
+  }
+}
+
+/**
+ * Verify a migration sequence
+ *
+ * Applies a sequence of migrations and verifies the final state.
+ *
+ * @example
+ * ```typescript
+ * await verifyMigrationSequence(executor, {
+ *   migrations: [migration1, migration2, migration3],
+ *   expectedTables: ['users', 'posts', 'comments'],
+ *   assertions: async (db) => {
+ *     expect(await db.getColumns('users')).toContain('email')
+ *   },
+ * })
+ * ```
+ */
+export async function verifyMigrationSequence(
+  executor: QueryExecutor,
+  options: {
+    migrations: Migration[]
+    expectedTables?: string[]
+    expectedVersion?: number
+    assertions?: (db: TestDatabase) => Promise<void>
+    tableName?: string
+    debug?: boolean
+  }
+): Promise<{ success: boolean; error?: Error }> {
+  const {
+    migrations,
+    expectedTables,
+    expectedVersion,
+    assertions,
+    tableName = '_test_migrations',
+    debug = false,
+  } = options
+
+  try {
+    const ctx = await createTestContext(executor, {
+      migrations,
+      tableName,
+      debug,
+    })
+
+    // Run all migrations
+    const result = await ctx.migrate()
+
+    if (!result.success) {
+      return {
+        success: false,
+        error: new Error(`Migration sequence failed: ${result.results.find((r) => !r.success)?.error}`),
+      }
+    }
+
+    // Verify expected tables
+    if (expectedTables) {
+      const tables = await ctx.db.getTables()
+      for (const table of expectedTables) {
+        if (!tables.includes(table)) {
+          return {
+            success: false,
+            error: new Error(`Expected table '${table}' not found`),
+          }
+        }
+      }
+    }
+
+    // Verify expected version
+    if (expectedVersion !== undefined) {
+      const version = await ctx.getVersion()
+      if (version !== expectedVersion) {
+        return {
+          success: false,
+          error: new Error(`Expected version ${expectedVersion}, got ${version}`),
+        }
+      }
+    }
+
+    // Run custom assertions
+    if (assertions) {
+      await assertions(ctx.db)
+    }
+
+    // Cleanup
+    await ctx.cleanup()
+
+    return { success: true }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+    }
+  }
+}
+
+/**
+ * Test rollback for a migration sequence
+ *
+ * @example
+ * ```typescript
+ * await testRollbackSequence(executor, {
+ *   migrations: [m1, m2, m3],
+ *   rollbackToVersion: 1,
+ *   afterRollback: async (db) => {
+ *     expect(await db.tableExists('users')).toBe(true)
+ *     expect(await db.tableExists('posts')).toBe(false)
+ *   },
+ * })
+ * ```
+ */
+export async function testRollbackSequence(
+  executor: QueryExecutor,
+  options: {
+    migrations: Migration[]
+    rollbackToVersion: number
+    afterRollback?: (db: TestDatabase) => Promise<void>
+    tableName?: string
+    debug?: boolean
+  }
+): Promise<{ success: boolean; rollbackResult?: BatchRollbackResult; error?: Error }> {
+  const {
+    migrations,
+    rollbackToVersion,
+    afterRollback,
+    tableName = '_test_migrations',
+    debug = false,
+  } = options
+
+  try {
+    const ctx = await createTestContext(executor, {
+      migrations,
+      tableName,
+      debug,
+    })
+
+    // Apply all migrations first
+    const migrateResult = await ctx.migrate()
+    if (!migrateResult.success) {
+      return {
+        success: false,
+        error: new Error('Failed to apply migrations before rollback test'),
+      }
+    }
+
+    // Perform rollback
+    const rollbackResult = await ctx.rollback(rollbackToVersion)
+
+    if (!rollbackResult.success) {
+      return {
+        success: false,
+        rollbackResult,
+        error: new Error(`Rollback failed: ${rollbackResult.results.find((r) => !r.success)?.error}`),
+      }
+    }
+
+    // Verify state after rollback
+    if (afterRollback) {
+      await afterRollback(ctx.db)
+    }
+
+    // Verify version
+    const version = await ctx.getVersion()
+    if (version !== rollbackToVersion) {
+      return {
+        success: false,
+        rollbackResult,
+        error: new Error(`Expected version ${rollbackToVersion} after rollback, got ${version}`),
+      }
+    }
+
+    // Cleanup
+    await ctx.cleanup()
+
+    return { success: true, rollbackResult }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+    }
+  }
+}
+
+// ============================================================================
+// Assertion Helpers
+// ============================================================================
+
+/**
+ * Assert that a table exists
+ */
+export async function assertTableExists(
+  db: TestDatabase,
+  tableName: string,
+  message?: string
+): Promise<void> {
+  const exists = await db.tableExists(tableName)
+  if (!exists) {
+    throw new Error(message || `Expected table '${tableName}' to exist`)
+  }
+}
+
+/**
+ * Assert that a table does not exist
+ */
+export async function assertTableNotExists(
+  db: TestDatabase,
+  tableName: string,
+  message?: string
+): Promise<void> {
+  const exists = await db.tableExists(tableName)
+  if (exists) {
+    throw new Error(message || `Expected table '${tableName}' to not exist`)
+  }
+}
+
+/**
+ * Assert that a table has specific columns
+ */
+export async function assertTableHasColumns(
+  db: TestDatabase,
+  tableName: string,
+  expectedColumns: string[],
+  message?: string
+): Promise<void> {
+  const columns = await db.getColumns(tableName)
+  for (const col of expectedColumns) {
+    if (!columns.includes(col)) {
+      throw new Error(message || `Expected table '${tableName}' to have column '${col}'`)
+    }
+  }
+}
+
+/**
+ * Assert that an index exists
+ */
+export async function assertIndexExists(
+  db: TestDatabase,
+  indexName: string,
+  message?: string
+): Promise<void> {
+  const exists = await db.indexExists(indexName)
+  if (!exists) {
+    throw new Error(message || `Expected index '${indexName}' to exist`)
+  }
+}
+
+/**
+ * Assert row count for a table
+ */
+export async function assertRowCount(
+  db: TestDatabase,
+  tableName: string,
+  expectedCount: number,
+  message?: string
+): Promise<void> {
+  const count = await db.getRowCount(tableName)
+  if (count !== expectedCount) {
+    throw new Error(
+      message || `Expected ${expectedCount} rows in '${tableName}', got ${count}`
+    )
+  }
+}
+
+// ============================================================================
+// Mock Executor
+// ============================================================================
+
+/**
+ * Create a mock query executor for unit testing
+ *
+ * This is useful for testing migration logic without a real database.
+ *
+ * @example
+ * ```typescript
+ * const executor = createMockExecutor({
+ *   queryResults: [
+ *     { query: /CREATE TABLE/, result: { rows: [], fields: [] } },
+ *     { query: /SELECT.*FROM.*_migrations/, result: { rows: [], fields: [] } },
+ *   ],
+ * })
+ * ```
+ */
+export function createMockExecutor(options: {
+  queryResults?: Array<{
+    query: RegExp | string
+    result: { rows: unknown[]; fields: { name: string; dataTypeID: number }[] }
+  }>
+  onQuery?: (sql: string, params?: unknown[]) => void
+} = {}): QueryExecutor {
+  const { queryResults = [], onQuery } = options
+  const executedQueries: Array<{ sql: string; params?: unknown[] }> = []
+
+  return {
+    async query<T = unknown>(sql: string, params?: unknown[]) {
+      const queryRecord: { sql: string; params?: unknown[] } = { sql }
+      if (params !== undefined) {
+        queryRecord.params = params
+      }
+      executedQueries.push(queryRecord)
+      onQuery?.(sql, params)
+
+      // Find matching result
+      for (const { query, result } of queryResults) {
+        if (typeof query === 'string') {
+          if (sql.includes(query)) {
+            return result as { rows: T[]; fields: { name: string; dataTypeID: number }[] }
+          }
+        } else {
+          if (query.test(sql)) {
+            return result as { rows: T[]; fields: { name: string; dataTypeID: number }[] }
+          }
+        }
+      }
+
+      // Default empty result
+      return { rows: [] as T[], fields: [] }
+    },
+
+    // Expose executed queries for assertions
+    getExecutedQueries(): Array<{ sql: string; params?: unknown[] }> {
+      return executedQueries
+    },
+  } as QueryExecutor & { getExecutedQueries(): Array<{ sql: string; params?: unknown[] }> }
+}