@dotdo/postgres 0.1.0

package/dist/migrations/do-migrations.js

@@ -0,0 +1,1060 @@
+/**
+ * DO Migration System
+ *
+ * Durable Object-specific migration system designed for:
+ * - Fast, idempotent migrations (called on every request)
+ * - Memory-efficient for Workers environment
+ * - Support for schema snapshots for fast bootstrapping
+ * - Concurrent access protection with advisory locking
+ *
+ * @module migrations/do-migrations
+ */
+import { createLogger, LogLevel } from '@dotdo/postgres-shared';
+import { ValidationError, InvalidIdentifierError, StateError } from '@dotdo/postgres-shared/errors';
+// =============================================================================
+// Constants
+// =============================================================================
+const DEFAULT_META_TABLE = '_do_migrations';
+const DEFAULT_LOCK_TIMEOUT_MS = 5000;
+const DEFAULT_MIGRATION_TIMEOUT_MS = 30000;
+const LOCK_KEY = 1; // Advisory lock key for migrations
+// Module-level logger for DO migrations
+// 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 doMigrationLogger = createLogger({
+    level: LogLevel.DEBUG,
+    prefix: '[DOMigration]',
+});
+// Regex pattern for valid SQL identifiers (alphanumeric + underscore, starting with letter or underscore)
+const VALID_SQL_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Validate that a string is a safe SQL identifier to prevent SQL injection.
+ * Must start with a letter or underscore, followed by letters, numbers, or underscores.
+ */
+function isValidSqlIdentifier(name) {
+    return VALID_SQL_IDENTIFIER_PATTERN.test(name);
+}
+// =============================================================================
+// Type Guards for MigrationExecutor
+// =============================================================================
+/**
+ * Type guard to check if executor is a plain SQL string
+ */
+function isStringExecutor(executor) {
+    return typeof executor === 'string';
+}
+/**
+ * Type guard to check if executor is a function that returns SQL
+ * These are zero-arity functions that return string or Promise<string>
+ */
+function isSqlFunctionExecutor(executor) {
+    if (typeof executor !== 'function')
+        return false;
+    // Check function signature - no parameters means SQL function
+    return executor.length === 0;
+}
+/**
+ * Type guard to check if executor is a function that operates on the database directly
+ * These are functions that take a PGlite instance and execute operations
+ */
+function isDbFunctionExecutor(executor) {
+    if (typeof executor !== 'function')
+        return false;
+    // Check function signature - one parameter means DB function
+    return executor.length === 1;
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Calculate a cryptographic checksum for migration content using SHA-256
+ */
+async function calculateChecksum(content) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(content);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    const hashArray = new Uint8Array(hashBuffer);
+    // Use first 16 bytes (32 hex chars) for reasonable uniqueness
+    return Array.from(hashArray.slice(0, 16))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Execute a migration executor
+ */
+async function executeExecutor(executor, db) {
+    if (isStringExecutor(executor)) {
+        await db.exec(executor);
+        return;
+    }
+    if (isDbFunctionExecutor(executor)) {
+        // Function expects db parameter - executes directly
+        await executor(db);
+        return;
+    }
+    if (isSqlFunctionExecutor(executor)) {
+        // Function returns SQL string
+        const sql = await executor();
+        await db.exec(sql);
+        return;
+    }
+    throw new ValidationError('Invalid executor type', {
+        code: 'INVALID_TYPE',
+        context: { executorType: typeof executor },
+    });
+}
+/**
+ * Get checksum content for a migration
+ */
+function getMigrationChecksumContent(migration) {
+    const upContent = typeof migration.up === 'string' ? migration.up : migration.up.toString();
+    const downContent = migration.down
+        ? (typeof migration.down === 'string' ? migration.down : migration.down.toString())
+        : '';
+    return `v${migration.version}:${migration.name}:${upContent}:${downContent}`;
+}
+// =============================================================================
+// DOMigrationRunner Implementation
+// =============================================================================
+class DOMigrationRunnerImpl {
+    _state = 'uninitialized';
+    db;
+    migrations;
+    config;
+    eventHandlers = new Set();
+    cachedVersion = null;
+    isInitialized = false;
+    constructor(db, migrations, config) {
+        // Validate metaTableName to prevent SQL injection
+        const metaTableName = config?.metaTableName ?? DEFAULT_META_TABLE;
+        if (!isValidSqlIdentifier(metaTableName)) {
+            throw new InvalidIdentifierError(metaTableName, 'table', 'Must be a valid SQL identifier (start with letter or underscore, contain only letters, numbers, and underscores)');
+        }
+        this.db = db;
+        this.migrations = [...migrations].sort((a, b) => a.version - b.version);
+        this.config = {
+            metaTableName,
+            useLocking: config?.useLocking ?? true,
+            lockTimeoutMs: config?.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS,
+            migrationTimeoutMs: config?.migrationTimeoutMs ?? DEFAULT_MIGRATION_TIMEOUT_MS,
+            useSnapshot: config?.useSnapshot ?? false,
+            allowVersionGaps: config?.allowVersionGaps ?? false,
+            debug: config?.debug ?? false,
+            dryRun: config?.dryRun ?? false,
+            ...(config?.snapshot !== undefined && { snapshot: config.snapshot }),
+            ...(config?.onEvent !== undefined && { onEvent: config.onEvent }),
+        };
+        if (config?.onEvent) {
+            this.eventHandlers.add(config.onEvent);
+        }
+    }
+    get state() {
+        return this._state;
+    }
+    emit(type, data) {
+        const event = {
+            type,
+            timestamp: new Date(),
+            ...data,
+        };
+        this.eventHandlers.forEach(handler => {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                // Don't let event handler errors break migration
+                if (this.config.debug) {
+                    doMigrationLogger.error('Event handler error', {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        });
+    }
+    async acquireLock() {
+        if (!this.config.useLocking) {
+            return true;
+        }
+        try {
+            // Use pg_try_advisory_lock with timeout
+            const startTime = Date.now();
+            while (Date.now() - startTime < this.config.lockTimeoutMs) {
+                const result = await this.db.query(`SELECT pg_try_advisory_lock(${LOCK_KEY})`);
+                if (result.rows[0]?.pg_try_advisory_lock) {
+                    this.emit('lock:acquired');
+                    return true;
+                }
+                // Wait a bit before retrying
+                await new Promise(resolve => setTimeout(resolve, 50));
+            }
+            this.emit('lock:timeout');
+            return false;
+        }
+        catch (error) {
+            // If advisory locks aren't supported, proceed without locking
+            if (this.config.debug) {
+                doMigrationLogger.warn('Advisory lock not available, proceeding without lock');
+            }
+            return true;
+        }
+    }
+    async releaseLock() {
+        if (!this.config.useLocking) {
+            return;
+        }
+        try {
+            await this.db.query(`SELECT pg_advisory_unlock(${LOCK_KEY})`);
+            this.emit('lock:released');
+        }
+        catch (error) {
+            // Ignore unlock errors
+            if (this.config.debug) {
+                doMigrationLogger.warn('Failed to release advisory lock', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    async initialize() {
+        if (this.isInitialized) {
+            return;
+        }
+        this._state = 'initializing';
+        try {
+            // Create migrations meta table if not exists
+            await this.db.exec(`
+        CREATE TABLE IF NOT EXISTS ${this.config.metaTableName} (
+          version INTEGER PRIMARY KEY,
+          name TEXT NOT NULL,
+          checksum TEXT NOT NULL,
+          applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+          execution_time_ms INTEGER
+        )
+      `);
+            this.isInitialized = true;
+            this._state = 'ready';
+            this.emit('initialized');
+        }
+        catch (error) {
+            this._state = 'error';
+            throw error;
+        }
+    }
+    async migrate() {
+        const startTime = Date.now();
+        const results = [];
+        let fromVersion = await this.getCurrentVersion();
+        let migrationsRun = 0;
+        let migrationsSkipped = 0;
+        if (!this.isInitialized) {
+            await this.initialize();
+        }
+        const pendingMigrations = await this.getPendingMigrations();
+        if (pendingMigrations.length === 0) {
+            return {
+                success: true,
+                fromVersion,
+                toVersion: fromVersion,
+                totalTimeMs: Date.now() - startTime,
+                results: [],
+                migrationsRun: 0,
+                migrationsSkipped: 0,
+            };
+        }
+        // Acquire lock
+        const lockAcquired = await this.acquireLock();
+        if (!lockAcquired) {
+            return {
+                success: false,
+                fromVersion,
+                toVersion: fromVersion,
+                totalTimeMs: Date.now() - startTime,
+                results: [],
+                migrationsRun: 0,
+                migrationsSkipped: 0,
+                error: 'Failed to acquire migration lock',
+            };
+        }
+        this._state = 'migrating';
+        this.emit('batch:start', { metadata: { fromVersion, pendingCount: pendingMigrations.length } });
+        try {
+            // Re-check pending migrations after acquiring lock (another process may have run them)
+            const actualPendingMigrations = await this.getPendingMigrations();
+            for (const migration of actualPendingMigrations) {
+                const migrationStartTime = Date.now();
+                this.emit('migration:start', { version: migration.version, name: migration.name });
+                try {
+                    if (this.config.dryRun) {
+                        // In dry-run mode, just record what would be done
+                        results.push({
+                            success: true,
+                            version: migration.version,
+                            name: migration.name,
+                            executionTimeMs: 0,
+                            skipped: true,
+                        });
+                        migrationsSkipped++;
+                        this.emit('migration:skip', { version: migration.version, name: migration.name });
+                        continue;
+                    }
+                    const transactional = migration.transactional !== false;
+                    if (transactional) {
+                        await this.db.exec('BEGIN');
+                    }
+                    try {
+                        await executeExecutor(migration.up, this.db);
+                        // Record the migration
+                        const checksum = await calculateChecksum(getMigrationChecksumContent(migration));
+                        const executionTimeMs = Date.now() - migrationStartTime;
+                        await this.db.query(`INSERT INTO ${this.config.metaTableName} (version, name, checksum, execution_time_ms) VALUES ($1, $2, $3, $4)`, [migration.version, migration.name, checksum, executionTimeMs]);
+                        if (transactional) {
+                            await this.db.exec('COMMIT');
+                        }
+                        results.push({
+                            success: true,
+                            version: migration.version,
+                            name: migration.name,
+                            executionTimeMs,
+                            checksum,
+                        });
+                        migrationsRun++;
+                        this.cachedVersion = migration.version;
+                        this.emit('migration:complete', {
+                            version: migration.version,
+                            name: migration.name,
+                            durationMs: executionTimeMs,
+                        });
+                    }
+                    catch (error) {
+                        if (transactional) {
+                            await this.db.exec('ROLLBACK');
+                        }
+                        throw error;
+                    }
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    const executionTimeMs = Date.now() - migrationStartTime;
+                    results.push({
+                        success: false,
+                        version: migration.version,
+                        name: migration.name,
+                        executionTimeMs,
+                        error: errorMessage,
+                    });
+                    this.emit('migration:error', {
+                        version: migration.version,
+                        name: migration.name,
+                        error: error instanceof Error ? error : new Error(errorMessage),
+                        durationMs: executionTimeMs,
+                    });
+                    // Stop on first failure
+                    break;
+                }
+            }
+            const toVersion = await this.getCurrentVersion();
+            const success = results.every(r => r.success);
+            this._state = success ? 'ready' : 'error';
+            const failedResult = results.find(r => !r.success);
+            const batchResult = {
+                success,
+                fromVersion,
+                toVersion,
+                totalTimeMs: Date.now() - startTime,
+                results,
+                migrationsRun,
+                migrationsSkipped,
+                ...(failedResult?.error !== undefined && { error: failedResult.error }),
+            };
+            this.emit(success ? 'batch:complete' : 'batch:error', {
+                durationMs: batchResult.totalTimeMs,
+                metadata: { fromVersion, toVersion, migrationsRun, migrationsSkipped },
+                ...(batchResult.error !== undefined && { error: new Error(batchResult.error) }),
+            });
+            return batchResult;
+        }
+        finally {
+            await this.releaseLock();
+        }
+    }
+    async ensureMigrated() {
+        if (!this.isInitialized) {
+            await this.initialize();
+        }
+        // Check if snapshot should be used for new DOs
+        if (this.config.useSnapshot && this.config.snapshot) {
+            const currentVersion = await this.getCurrentVersion();
+            if (currentVersion === 0) {
+                // New DO - use snapshot
+                return this.applySnapshot(this.config.snapshot);
+            }
+        }
+        return this.migrate();
+    }
+    async applySnapshot(snapshot) {
+        const startTime = Date.now();
+        // Validate snapshot checksum
+        const currentChecksum = await this.calculateMigrationsChecksum();
+        if (snapshot.migrationsChecksum !== currentChecksum) {
+            // Snapshot is stale, fall back to incremental migrations
+            if (this.config.debug) {
+                doMigrationLogger.warn('Snapshot checksum mismatch, falling back to incremental migrations');
+            }
+            return this.migrate();
+        }
+        const lockAcquired = await this.acquireLock();
+        if (!lockAcquired) {
+            return {
+                success: false,
+                fromVersion: 0,
+                toVersion: 0,
+                totalTimeMs: Date.now() - startTime,
+                results: [],
+                migrationsRun: 0,
+                migrationsSkipped: 0,
+                error: 'Failed to acquire migration lock',
+            };
+        }
+        this._state = 'migrating';
+        try {
+            await this.db.exec('BEGIN');
+            try {
+                // Apply schema DDL
+                await this.db.exec(snapshot.schemaDDL);
+                // Apply seed data if present
+                if (snapshot.seedDataDDL) {
+                    await this.db.exec(snapshot.seedDataDDL);
+                }
+                // Record all migration versions
+                for (const version of snapshot.includedVersions) {
+                    const migration = this.migrations.find(m => m.version === version);
+                    if (migration) {
+                        const checksum = await calculateChecksum(getMigrationChecksumContent(migration));
+                        await this.db.query(`INSERT INTO ${this.config.metaTableName} (version, name, checksum, execution_time_ms) VALUES ($1, $2, $3, $4)`, [migration.version, migration.name, checksum, 0]);
+                    }
+                }
+                await this.db.exec('COMMIT');
+                this.cachedVersion = snapshot.targetVersion;
+                this._state = 'ready';
+                this.emit('snapshot:applied', {
+                    metadata: { targetVersion: snapshot.targetVersion, includedVersions: snapshot.includedVersions },
+                });
+                return {
+                    success: true,
+                    fromVersion: 0,
+                    toVersion: snapshot.targetVersion,
+                    totalTimeMs: Date.now() - startTime,
+                    results: snapshot.includedVersions.map(v => {
+                        const m = this.migrations.find(m => m.version === v);
+                        return {
+                            success: true,
+                            version: v,
+                            name: m?.name ?? `migration_${v}`,
+                            executionTimeMs: 0,
+                            skipped: false,
+                        };
+                    }),
+                    migrationsRun: snapshot.includedVersions.length,
+                    migrationsSkipped: 0,
+                };
+            }
+            catch (error) {
+                await this.db.exec('ROLLBACK');
+                throw error;
+            }
+        }
+        catch (error) {
+            this._state = 'error';
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Fall back to incremental migrations
+            if (this.config.debug) {
+                doMigrationLogger.warn('Snapshot application failed, falling back to incremental migrations', {
+                    error: errorMessage,
+                });
+            }
+            return this.migrate();
+        }
+        finally {
+            await this.releaseLock();
+        }
+    }
+    async calculateMigrationsChecksum() {
+        const content = this.migrations
+            .map(m => getMigrationChecksumContent(m))
+            .join('|');
+        return await calculateChecksum(content);
+    }
+    async getCurrentVersion() {
+        if (this.cachedVersion !== null) {
+            return this.cachedVersion;
+        }
+        if (!this.isInitialized) {
+            await this.initialize();
+        }
+        try {
+            const result = await this.db.query(`SELECT MAX(version) as max FROM ${this.config.metaTableName}`);
+            const version = result.rows[0]?.max ?? 0;
+            this.cachedVersion = version;
+            return version;
+        }
+        catch (error) {
+            // Table might not exist yet
+            return 0;
+        }
+    }
+    async getSchemaVersion() {
+        if (!this.isInitialized) {
+            await this.initialize();
+        }
+        try {
+            const result = await this.db.query(`
+        SELECT
+          MAX(version) as current_version,
+          COUNT(*) as applied_count,
+          MAX(applied_at) as last_migration_at
+        FROM ${this.config.metaTableName}
+      `);
+            const row = result.rows[0];
+            const currentVersion = row?.current_version ?? 0;
+            const appliedCount = Number(row?.applied_count ?? 0);
+            const lastMigrationAt = row?.last_migration_at ? new Date(row.last_migration_at) : null;
+            // Calculate schema checksum from applied migrations
+            const appliedMigrations = await this.getAppliedMigrations();
+            const schemaChecksum = appliedMigrations.length > 0
+                ? await calculateChecksum(appliedMigrations.map(m => m.checksum).join('|'))
+                : null;
+            return {
+                currentVersion,
+                appliedCount,
+                lastMigrationAt,
+                schemaChecksum,
+            };
+        }
+        catch (error) {
+            return {
+                currentVersion: 0,
+                appliedCount: 0,
+                lastMigrationAt: null,
+                schemaChecksum: null,
+            };
+        }
+    }
+    async getPendingMigrations() {
+        const currentVersion = await this.getCurrentVersion();
+        const appliedVersions = new Set((await this.getAppliedMigrations()).map(m => m.version));
+        return this.migrations.filter(m => m.version > currentVersion || !appliedVersions.has(m.version));
+    }
+    async hasPendingMigrations() {
+        const pending = await this.getPendingMigrations();
+        return pending.length > 0;
+    }
+    async rollbackTo(targetVersion, options) {
+        const startTime = Date.now();
+        const currentVersion = await this.getCurrentVersion();
+        const results = [];
+        if (targetVersion >= currentVersion) {
+            return {
+                success: true,
+                fromVersion: currentVersion,
+                toVersion: currentVersion,
+                totalTimeMs: Date.now() - startTime,
+                results: [],
+                migrationsRun: 0,
+                migrationsSkipped: 0,
+            };
+        }
+        // Get migrations to rollback (in reverse order)
+        const migrationsToRollback = this.migrations
+            .filter(m => m.version > targetVersion && m.version <= currentVersion)
+            .sort((a, b) => b.version - a.version);
+        // Check for non-reversible migrations
+        if (!options?.force) {
+            const nonReversible = migrationsToRollback.find(m => m.isReversible === false || (!m.down && m.isReversible !== true));
+            if (nonReversible) {
+                return {
+                    success: false,
+                    fromVersion: currentVersion,
+                    toVersion: currentVersion,
+                    totalTimeMs: Date.now() - startTime,
+                    results: [],
+                    migrationsRun: 0,
+                    migrationsSkipped: 0,
+                    error: `Migration ${nonReversible.version} (${nonReversible.name}) is not reversible. Use force option to skip.`,
+                };
+            }
+        }
+        if (options?.dryRun) {
+            return {
+                success: true,
+                fromVersion: currentVersion,
+                toVersion: targetVersion,
+                totalTimeMs: Date.now() - startTime,
+                results: migrationsToRollback.map(m => ({
+                    success: true,
+                    version: m.version,
+                    name: m.name,
+                    executionTimeMs: 0,
+                    skipped: true,
+                })),
+                migrationsRun: 0,
+                migrationsSkipped: migrationsToRollback.length,
+            };
+        }
+        const lockAcquired = await this.acquireLock();
+        if (!lockAcquired) {
+            return {
+                success: false,
+                fromVersion: currentVersion,
+                toVersion: currentVersion,
+                totalTimeMs: Date.now() - startTime,
+                results: [],
+                migrationsRun: 0,
+                migrationsSkipped: 0,
+                error: 'Failed to acquire migration lock',
+            };
+        }
+        this._state = 'migrating';
+        try {
+            let migrationsRun = 0;
+            let migrationsSkipped = 0;
+            for (const migration of migrationsToRollback) {
+                const migrationStartTime = Date.now();
+                if (!migration.down) {
+                    // Skip migrations without down
+                    results.push({
+                        success: true,
+                        version: migration.version,
+                        name: migration.name,
+                        executionTimeMs: 0,
+                        skipped: true,
+                    });
+                    migrationsSkipped++;
+                    if (options?.onProgress) {
+                        options.onProgress({
+                            type: 'migration:skip',
+                            timestamp: new Date(),
+                            version: migration.version,
+                            name: migration.name,
+                        });
+                    }
+                    continue;
+                }
+                try {
+                    const transactional = migration.transactional !== false;
+                    if (transactional) {
+                        await this.db.exec('BEGIN');
+                    }
+                    try {
+                        await executeExecutor(migration.down, this.db);
+                        // Remove the migration record
+                        await this.db.query(`DELETE FROM ${this.config.metaTableName} WHERE version = $1`, [migration.version]);
+                        if (transactional) {
+                            await this.db.exec('COMMIT');
+                        }
+                        const executionTimeMs = Date.now() - migrationStartTime;
+                        results.push({
+                            success: true,
+                            version: migration.version,
+                            name: migration.name,
+                            executionTimeMs,
+                        });
+                        migrationsRun++;
+                        if (options?.onProgress) {
+                            options.onProgress({
+                                type: 'migration:complete',
+                                timestamp: new Date(),
+                                version: migration.version,
+                                name: migration.name,
+                                durationMs: executionTimeMs,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        if (transactional) {
+                            await this.db.exec('ROLLBACK');
+                        }
+                        throw error;
+                    }
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    results.push({
+                        success: false,
+                        version: migration.version,
+                        name: migration.name,
+                        executionTimeMs: Date.now() - migrationStartTime,
+                        error: errorMessage,
+                    });
+                    if (options?.onProgress) {
+                        options.onProgress({
+                            type: 'migration:error',
+                            timestamp: new Date(),
+                            version: migration.version,
+                            name: migration.name,
+                            error: error instanceof Error ? error : new Error(errorMessage),
+                        });
+                    }
+                    // Stop on first failure
+                    break;
+                }
+            }
+            // Invalidate cache
+            this.cachedVersion = null;
+            const toVersion = await this.getCurrentVersion();
+            const success = results.every(r => r.success);
+            this._state = success ? 'ready' : 'error';
+            const failedError = results.find(r => !r.success)?.error;
+            const result = {
+                success,
+                fromVersion: currentVersion,
+                toVersion,
+                totalTimeMs: Date.now() - startTime,
+                results,
+                migrationsRun,
+                migrationsSkipped,
+            };
+            if (failedError !== undefined) {
+                result.error = failedError;
+            }
+            return result;
+        }
+        finally {
+            await this.releaseLock();
+        }
+    }
+    async rollbackLast(count = 1, options) {
+        const currentVersion = await this.getCurrentVersion();
+        const appliedMigrations = await this.getAppliedMigrations();
+        // Sort by version descending and take the last 'count' migrations
+        const toRollback = appliedMigrations
+            .sort((a, b) => b.version - a.version)
+            .slice(0, count);
+        if (toRollback.length === 0) {
+            return {
+                success: true,
+                fromVersion: currentVersion,
+                toVersion: currentVersion,
+                totalTimeMs: 0,
+                results: [],
+                migrationsRun: 0,
+                migrationsSkipped: 0,
+            };
+        }
+        // Find the target version (one less than the lowest version to rollback)
+        const lowestVersion = Math.min(...toRollback.map(m => m.version));
+        const targetVersion = this.migrations
+            .filter(m => m.version < lowestVersion)
+            .reduce((max, m) => Math.max(max, m.version), 0);
+        return this.rollbackTo(targetVersion, options);
+    }
+    async reset() {
+        const lockAcquired = await this.acquireLock();
+        if (!lockAcquired) {
+            throw new StateError('Failed to acquire migration lock for reset', {
+                currentState: 'locked',
+                expectedStates: ['unlocked'],
+            });
+        }
+        try {
+            await this.db.exec(`DROP TABLE IF EXISTS ${this.config.metaTableName}`);
+            this.cachedVersion = null;
+            this.isInitialized = false;
+            this._state = 'uninitialized';
+        }
+        finally {
+            await this.releaseLock();
+        }
+    }
+    async validate() {
+        const issues = [];
+        // Check for required fields
+        for (const migration of this.migrations) {
+            if (typeof migration.version !== 'number' || migration.version < 1) {
+                issues.push({
+                    severity: 'error',
+                    version: migration.version,
+                    message: `Migration version must be a positive integer, got: ${migration.version}`,
+                    suggestion: 'Use a positive integer for the version field',
+                });
+            }
+            if (!migration.name || typeof migration.name !== 'string') {
+                issues.push({
+                    severity: 'error',
+                    version: migration.version,
+                    message: 'Migration name is required and must be a non-empty string',
+                    suggestion: 'Add a descriptive name for the migration',
+                });
+            }
+            if (migration.up === undefined ||
+                (typeof migration.up !== 'string' && typeof migration.up !== 'function')) {
+                issues.push({
+                    severity: 'error',
+                    version: migration.version,
+                    message: 'Migration up must be a string or function',
+                    suggestion: 'Provide SQL string or function for the up migration',
+                });
+            }
+            if (migration.down !== undefined &&
+                typeof migration.down !== 'string' &&
+                typeof migration.down !== 'function') {
+                issues.push({
+                    severity: 'error',
+                    version: migration.version,
+                    message: 'Migration down must be a string or function if provided',
+                    suggestion: 'Provide SQL string or function for the down migration',
+                });
+            }
+            // Warning for missing down migration
+            if (!migration.down && migration.isReversible !== false) {
+                issues.push({
+                    severity: 'warning',
+                    version: migration.version,
+                    message: 'Migration has no down migration defined',
+                    suggestion: 'Add a down migration or set isReversible: false',
+                });
+            }
+        }
+        // Check for duplicate versions
+        const versions = new Set();
+        for (const migration of this.migrations) {
+            if (versions.has(migration.version)) {
+                issues.push({
+                    severity: 'error',
+                    version: migration.version,
+                    message: `Duplicate migration version: ${migration.version}`,
+                    suggestion: 'Use unique version numbers for each migration',
+                });
+            }
+            versions.add(migration.version);
+        }
+        // Check for sequential versions (if not allowing gaps)
+        if (!this.config.allowVersionGaps) {
+            const sortedVersions = Array.from(versions).sort((a, b) => a - b);
+            for (let i = 1; i < sortedVersions.length; i++) {
+                const currentVersion = sortedVersions[i];
+                const previousVersion = sortedVersions[i - 1];
+                if (currentVersion !== previousVersion + 1) {
+                    issues.push({
+                        severity: 'warning',
+                        version: currentVersion,
+                        message: `Gap in version numbers between ${previousVersion} and ${currentVersion}`,
+                        suggestion: 'Use sequential version numbers or enable allowVersionGaps config',
+                    });
+                }
+            }
+        }
+        // Check for checksum mismatches with applied migrations
+        try {
+            const appliedMigrations = await this.getAppliedMigrations();
+            const appliedByVersion = new Map(appliedMigrations.map(m => [m.version, m]));
+            for (const migration of this.migrations) {
+                const applied = appliedByVersion.get(migration.version);
+                if (applied) {
+                    const currentChecksum = await calculateChecksum(getMigrationChecksumContent(migration));
+                    if (applied.checksum !== currentChecksum) {
+                        issues.push({
+                            severity: 'error',
+                            version: migration.version,
+                            message: `Migration ${migration.version} has been modified after being applied`,
+                            suggestion: 'Migrations should not be modified after being applied. Create a new migration instead.',
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // Meta table might not exist yet, skip checksum validation
+        }
+        const errorCount = issues.filter(i => i.severity === 'error').length;
+        const warningCount = issues.filter(i => i.severity === 'warning').length;
+        return {
+            valid: errorCount === 0,
+            issues,
+            errorCount,
+            warningCount,
+        };
+    }
+    getMigrations() {
+        return [...this.migrations];
+    }
+    getLatestVersion() {
+        if (this.migrations.length === 0) {
+            return 0;
+        }
+        return Math.max(...this.migrations.map(m => m.version));
+    }
+    async getAppliedMigrations() {
+        if (!this.isInitialized) {
+            await this.initialize();
+        }
+        try {
+            const result = await this.db.query(`
+        SELECT version, name, checksum, applied_at, execution_time_ms
+        FROM ${this.config.metaTableName}
+        ORDER BY version ASC
+      `);
+            return result.rows.map(row => ({
+                version: row.version,
+                name: row.name,
+                checksum: row.checksum,
+                appliedAt: new Date(row.applied_at),
+                executionTimeMs: row.execution_time_ms,
+            }));
+        }
+        catch (error) {
+            return [];
+        }
+    }
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => {
+            this.eventHandlers.delete(handler);
+        };
+    }
+}
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Create a DO migration runner
+ *
+ * @param db - PGlite database instance
+ * @param migrations - Array of migrations to manage
+ * @param config - Optional configuration for the runner
+ * @returns A configured DOMigrationRunner instance
+ *
+ * @example
+ * ```typescript
+ * import { createDOMigrationRunner } from './do-migrations'
+ *
+ * const migrations = [
+ *   {
+ *     version: 1,
+ *     name: 'create_users_table',
+ *     up: `CREATE TABLE users (
+ *       id SERIAL PRIMARY KEY,
+ *       email TEXT UNIQUE NOT NULL,
+ *       created_at TIMESTAMPTZ DEFAULT NOW()
+ *     )`,
+ *     down: 'DROP TABLE users',
+ *   },
+ *   {
+ *     version: 2,
+ *     name: 'add_users_name',
+ *     up: 'ALTER TABLE users ADD COLUMN name TEXT',
+ *     down: 'ALTER TABLE users DROP COLUMN name',
+ *   },
+ * ]
+ *
+ * const runner = createDOMigrationRunner(pglite, migrations, {
+ *   metaTableName: '_migrations',
+ *   useLocking: true,
+ * })
+ *
+ * // Run all pending migrations
+ * const result = await runner.migrate()
+ * console.log(`Migrated from v${result.fromVersion} to v${result.toVersion}`)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With event handlers for logging
+ * const runner = createDOMigrationRunner(pglite, migrations, {
+ *   onEvent: (event) => {
+ *     if (event.type === 'migration:complete') {
+ *       console.log(`Applied migration ${event.version}: ${event.name}`)
+ *     }
+ *   },
+ * })
+ * ```
+ */
+export const createDOMigrationRunner = (db, migrations, config) => {
+    if (!db) {
+        throw new ValidationError('Database instance is required', {
+            code: 'VALIDATION_ERROR',
+            fields: { db: 'Required parameter is missing' },
+        });
+    }
+    if (!migrations || !Array.isArray(migrations)) {
+        throw new ValidationError('Migrations array is required', {
+            code: 'VALIDATION_ERROR',
+            fields: { migrations: 'Must be an array' },
+        });
+    }
+    return new DOMigrationRunnerImpl(db, migrations, config);
+};
+/**
+ * Generate a schema snapshot from migrations
+ *
+ * Creates a consolidated schema DDL from a set of migrations for fast
+ * bootstrapping of new Durable Objects.
+ *
+ * @param migrations - Array of migrations to consolidate
+ * @param options - Optional configuration
+ * @returns Schema snapshot with DDL and metadata
+ *
+ * @example
+ * ```typescript
+ * import { generateDOSchemaSnapshot } from './do-migrations'
+ *
+ * const snapshot = await generateDOSchemaSnapshot(migrations, {
+ *   includeSeedData: true,
+ * })
+ *
+ * console.log(`Target version: ${snapshot.targetVersion}`)
+ * console.log(`Schema DDL:\n${snapshot.schemaDDL}`)
+ *
+ * // Use with runner for fast bootstrap
+ * const runner = createDOMigrationRunner(pglite, migrations, {
+ *   useSnapshot: true,
+ *   snapshot,
+ * })
+ * ```
+ */
+export const generateDOSchemaSnapshot = async (migrations, options) => {
+    const sortedMigrations = [...migrations].sort((a, b) => a.version - b.version);
+    const schemaSQLParts = [];
+    const seedDataSQLParts = [];
+    for (const migration of sortedMigrations) {
+        const sql = typeof migration.up === 'string'
+            ? migration.up
+            : migration.up.toString();
+        // Simple heuristic: seed data migrations often have INSERT statements
+        // and are tagged as 'seed' or 'data'
+        const isSeedData = migration.tags?.includes('seed') || migration.tags?.includes('data');
+        if (isSeedData && options?.includeSeedData) {
+            seedDataSQLParts.push(sql);
+        }
+        else {
+            schemaSQLParts.push(sql);
+        }
+    }
+    const targetVersion = sortedMigrations.length > 0
+        ? Math.max(...sortedMigrations.map(m => m.version))
+        : 0;
+    const migrationsChecksum = await calculateChecksum(sortedMigrations.map(m => getMigrationChecksumContent(m)).join('|'));
+    return {
+        targetVersion,
+        schemaDDL: schemaSQLParts.join('\n\n'),
+        migrationsChecksum,
+        includedVersions: sortedMigrations.map(m => m.version),
+        generatedAt: new Date(),
+        ...(seedDataSQLParts.length > 0 && { seedDataDDL: seedDataSQLParts.join('\n\n') }),
+    };
+};
+/**
+ * Convert standard Migration to DOMigration
+ */
+export const convertToDOMigration = (migration) => {
+    return {
+        version: migration.version,
+        name: migration.name,
+        up: migration.up,
+        ...(migration.down !== undefined && { down: migration.down }),
+        ...(migration.isReversible !== undefined && { isReversible: migration.isReversible }),
+        ...(migration.transactional !== undefined && { transactional: migration.transactional }),
+        ...(migration.timeoutMs !== undefined && { timeoutMs: migration.timeoutMs }),
+        ...(migration.tags !== undefined && { tags: migration.tags }),
+    };
+};
+//# sourceMappingURL=do-migrations.js.map