@dotdo/postgres 0.1.0

package/src/migrations/do-migrations.ts

@@ -0,0 +1,1289 @@
+/**
+ * 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 type { PGlite } from '@dotdo/pglite'
+import { createLogger, LogLevel, type ILogger } from '@dotdo/postgres-shared'
+import { ValidationError, InvalidIdentifierError, StateError } from '@dotdo/postgres-shared/errors'
+import type {
+  DOMigration,
+  DOMigrationRunner,
+  DOMigrationResult,
+  DOMigrationBatchResult,
+  DOMigrationConfig,
+  DOMigrationState,
+  DOSchemaVersion,
+  DOSchemaSnapshot,
+  DOMigrationRecord,
+  DOMigrationEvent,
+  DOMigrationEventType,
+  DOMigrationEventHandler,
+  DORollbackOptions,
+  DOMigrationValidationResult,
+  DOMigrationValidationIssue,
+  MigrationExecutor,
+  CreateDOMigrationRunner,
+  GenerateDOSchemaSnapshot,
+  ConvertToDOMigration,
+} from './do-migrations.types'
+
+// =============================================================================
+// 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: ILogger = 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: string): boolean {
+  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: MigrationExecutor): executor is string {
+  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: MigrationExecutor
+): executor is (() => string) | (() => Promise<string>) {
+  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: MigrationExecutor
+): executor is (db: PGlite) => Promise<void> {
+  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: string): Promise<string> {
+  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: MigrationExecutor, db: PGlite): Promise<void> {
+  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: DOMigration): string {
+  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 implements DOMigrationRunner {
+  private _state: DOMigrationState = 'uninitialized'
+  private readonly db: PGlite
+  private readonly migrations: DOMigration[]
+  private readonly config: Required<Omit<DOMigrationConfig, 'snapshot' | 'onEvent'>> & {
+    snapshot?: DOSchemaSnapshot
+    onEvent?: DOMigrationEventHandler
+  }
+  private readonly eventHandlers: Set<DOMigrationEventHandler> = new Set()
+  private cachedVersion: number | null = null
+  private isInitialized = false
+
+  constructor(db: PGlite, migrations: DOMigration[], config?: DOMigrationConfig) {
+    // 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(): DOMigrationState {
+    return this._state
+  }
+
+  private emit(type: DOMigrationEventType, data?: Partial<Omit<DOMigrationEvent, 'type' | 'timestamp'>>): void {
+    const event: DOMigrationEvent = {
+      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),
+          })
+        }
+      }
+    })
+  }
+
+  private async acquireLock(): Promise<boolean> {
+    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<{ pg_try_advisory_lock: boolean }>(
+          `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
+    }
+  }
+
+  private async releaseLock(): Promise<void> {
+    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(): Promise<void> {
+    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(): Promise<DOMigrationBatchResult> {
+    const startTime = Date.now()
+    const results: DOMigrationResult[] = []
+    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: DOMigrationBatchResult = {
+        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(): Promise<DOMigrationBatchResult> {
+    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()
+  }
+
+  private async applySnapshot(snapshot: DOSchemaSnapshot): Promise<DOMigrationBatchResult> {
+    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()
+    }
+  }
+
+  private async calculateMigrationsChecksum(): Promise<string> {
+    const content = this.migrations
+      .map(m => getMigrationChecksumContent(m))
+      .join('|')
+    return await calculateChecksum(content)
+  }
+
+  async getCurrentVersion(): Promise<number> {
+    if (this.cachedVersion !== null) {
+      return this.cachedVersion
+    }
+
+    if (!this.isInitialized) {
+      await this.initialize()
+    }
+
+    try {
+      const result = await this.db.query<{ max: number | null }>(
+        `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(): Promise<DOSchemaVersion> {
+    if (!this.isInitialized) {
+      await this.initialize()
+    }
+
+    try {
+      const result = await this.db.query<{
+        current_version: number | null
+        applied_count: number
+        last_migration_at: string | null
+      }>(`
+        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(): Promise<DOMigration[]> {
+    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(): Promise<boolean> {
+    const pending = await this.getPendingMigrations()
+    return pending.length > 0
+  }
+
+  async rollbackTo(targetVersion: number, options?: DORollbackOptions): Promise<DOMigrationBatchResult> {
+    const startTime = Date.now()
+    const currentVersion = await this.getCurrentVersion()
+    const results: DOMigrationResult[] = []
+
+    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: DOMigrationBatchResult = {
+        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?: DORollbackOptions): Promise<DOMigrationBatchResult> {
+    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(): Promise<void> {
+    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(): Promise<DOMigrationValidationResult> {
+    const issues: DOMigrationValidationIssue[] = []
+
+    // 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<number>()
+    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(): DOMigration[] {
+    return [...this.migrations]
+  }
+
+  getLatestVersion(): number {
+    if (this.migrations.length === 0) {
+      return 0
+    }
+    return Math.max(...this.migrations.map(m => m.version))
+  }
+
+  async getAppliedMigrations(): Promise<DOMigrationRecord[]> {
+    if (!this.isInitialized) {
+      await this.initialize()
+    }
+
+    try {
+      const result = await this.db.query<{
+        version: number
+        name: string
+        checksum: string
+        applied_at: string
+        execution_time_ms: number
+      }>(`
+        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: DOMigrationEventHandler): () => void {
+    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: CreateDOMigrationRunner = (
+  db: PGlite,
+  migrations: DOMigration[],
+  config?: DOMigrationConfig
+): DOMigrationRunner => {
+  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: GenerateDOSchemaSnapshot = async (
+  migrations: DOMigration[],
+  options?: { includeSeedData?: boolean }
+): Promise<DOSchemaSnapshot> => {
+  const sortedMigrations = [...migrations].sort((a, b) => a.version - b.version)
+
+  const schemaSQLParts: string[] = []
+  const seedDataSQLParts: string[] = []
+
+  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: ConvertToDOMigration = (migration): DOMigration => {
+  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 }),
+  }
+}
+
+// =============================================================================
+// Re-exports
+// =============================================================================
+
+export type {
+  DOMigration,
+  DOMigrationRunner,
+  DOMigrationResult,
+  DOMigrationBatchResult,
+  DOMigrationConfig,
+  DOMigrationState,
+  DOSchemaVersion,
+  DOSchemaSnapshot,
+  DOMigrationRecord,
+  DOMigrationEvent,
+  DOMigrationEventType,
+  DOMigrationEventHandler,
+  DORollbackOptions,
+  DOMigrationValidationResult,
+  DOMigrationValidationIssue,
+  MigrationExecutor,
+}