@dotdo/postgres 0.1.0

package/dist/migrations/runner.js

@@ -0,0 +1,1167 @@
+/**
+ * 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 { MigrationError } from '@dotdo/postgres-shared/errors';
+import { createLogger, LogLevel } from '@dotdo/postgres-shared';
+export { MigrationError };
+// 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 = createLogger({
+    level: LogLevel.DEBUG,
+    prefix: '[MigrationRunner]',
+});
+/**
+ * Default runner configuration
+ */
+const DEFAULT_CONFIG = {
+    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, schema) => `
+  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, schema) => `
+  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() {
+    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) {
+    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() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `lock_${timestamp}_${random}`;
+}
+export class MigrationRunner {
+    executor;
+    registry;
+    config;
+    onProgress;
+    initialized = false;
+    listeners = [];
+    rollbackListeners = [];
+    currentLock = null;
+    constructor(executor, registry, config = {}) {
+        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),
+            schema: (config.schema ?? DEFAULT_CONFIG.schema),
+            autoMigrate: (config.autoMigrate ?? DEFAULT_CONFIG.autoMigrate),
+            migrationTimeoutMs: (config.migrationTimeoutMs ?? DEFAULT_CONFIG.migrationTimeoutMs),
+            useLocking: (config.useLocking ?? DEFAULT_CONFIG.useLocking),
+            lockTimeoutMs: (config.lockTimeoutMs ?? DEFAULT_CONFIG.lockTimeoutMs),
+            debug: (config.debug ?? DEFAULT_CONFIG.debug),
+        };
+        this.onProgress = config.onProgress;
+    }
+    /**
+     * Log debug message
+     */
+    log(message, ...args) {
+        if (this.config.debug) {
+            runnerLogger.debug(message, args.length > 0 ? { args } : undefined);
+        }
+    }
+    /**
+     * Emit a migration event
+     */
+    async emitEvent(event) {
+        const fullEvent = {
+            ...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) {
+        this.listeners.push(listener);
+        return () => {
+            const index = this.listeners.indexOf(listener);
+            if (index >= 0) {
+                this.listeners.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Emit a rollback event
+     */
+    async emitRollbackEvent(event) {
+        const fullEvent = {
+            ...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) {
+        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
+     */
+    getTableName() {
+        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() {
+        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
+     */
+    getRollbackHistoryTableName() {
+        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.
+     */
+    async acquireLock() {
+        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(`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
+     */
+    async releaseLock() {
+        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() {
+        await this.initialize();
+        const result = await this.executor.query(`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((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() {
+        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 = [];
+        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) {
+        await this.initialize();
+        const result = await this.executor.query(`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) {
+        const record = await this.getMigrationRecord(id);
+        return record?.status === 'applied';
+    }
+    /**
+     * Apply a single migration
+     */
+    async applyMigration(migration, index, total) {
+        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 = {
+                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 = {
+                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() {
+        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 = [];
+            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 = {
+                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) {
+        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 = [];
+            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) {
+        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
+     */
+    async recordRollbackHistory(rollbackId, migration, previousStatus, executionTimeMs, reason) {
+        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() {
+        await this.initialize();
+        const result = await this.executor.query(`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) {
+        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 = [];
+        const blockers = [];
+        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 = {}) {
+        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 = {
+                    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 = {
+                    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) {
+        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 = [];
+            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 = {
+                        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 = {
+                        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 = {
+                        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 = {
+                        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 = {
+                        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 = {
+                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) {
+        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() {
+        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() {
+        return this.initialized;
+    }
+    /**
+     * Get the registry
+     */
+    getRegistry() {
+        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, registry, config = {}) {
+    return new MigrationRunner(executor, registry, config);
+}
+//# sourceMappingURL=runner.js.map