pg-migration-engine 0.1.0

package/src/storage/rollback-generator.js

@@ -0,0 +1,344 @@
+/**
+ * Rollback Generator - Generate rollback SQL for migrations
+ */
+
+export class RollbackGenerator {
+  /**
+   * Generate rollback SQL from a completed migration's history
+   * @param {Object} migration - Migration history record
+   * @returns {Array} Rollback SQL statements in reverse order
+   */
+  generateRollback(migration) {
+    const diff = migration.schema_diff || migration.diff;
+    const rollbackSteps = [];
+
+    if (!diff?.changes) {
+      return rollbackSteps;
+    }
+
+    const changes = [...diff.changes].reverse();
+
+    for (const change of changes) {
+      const undoSQL = this.generateUndoForChange(change);
+      if (undoSQL) {
+        rollbackSteps.push({
+          sql: undoSQL,
+          originalChangeId: change.id,
+          changeType: change.changeType,
+          objectKey: change.objectKey || change.path,
+          isTransactional: change.isTransactional !== false,
+        });
+      }
+    }
+
+    return rollbackSteps;
+  }
+
+  /**
+   * Generate undo SQL for a single change
+   * @param {Object} change
+   * @returns {string|null}
+   */
+  generateUndoForChange(change) {
+    const changeType = change.changeType;
+    const objectType = change.objectType;
+    const path = change.objectKey || change.path;
+    const schema = change.schema;
+    const name = change.name;
+
+    switch (changeType) {
+      case 'CREATE':
+      case 'ADD':
+        return this.generateUndoForCreate(change, objectType, path);
+
+      case 'DROP':
+      case 'REMOVE':
+        return this.generateUndoForDrop(change, objectType, path);
+
+      case 'ALTER':
+        return this.generateUndoForAlter(change, objectType, path);
+
+      case 'RENAME':
+        return this.generateUndoForRename(change, path);
+
+      case 'RECREATE':
+      case 'REPLACE':
+        return this.generateUndoForReplace(change, objectType, path);
+
+      default:
+        if (changeType?.startsWith('CREATE')) {
+          return this.generateUndoForCreate(change, objectType, path);
+        }
+        if (changeType?.startsWith('DROP')) {
+          return this.generateUndoForDrop(change, objectType, path);
+        }
+        return `-- CANNOT AUTO-ROLLBACK: Unknown change type "${changeType}" for ${path}`;
+    }
+  }
+
+  /**
+   * Generate undo for CREATE operations
+   */
+  generateUndoForCreate(change, objectType, path) {
+    switch (objectType) {
+      case 'table':
+        return `DROP TABLE IF EXISTS ${path} CASCADE;`;
+
+      case 'index':
+        if (change.isConcurrent) {
+          return `DROP INDEX CONCURRENTLY IF EXISTS ${path};`;
+        }
+        return `DROP INDEX IF EXISTS ${path};`;
+
+      case 'constraint':
+        const conTable = change.after?.tableKey || change.schema;
+        const conName = change.after?.name || change.name;
+        return `ALTER TABLE ${conTable} DROP CONSTRAINT IF EXISTS ${conName};`;
+
+      case 'view':
+        return `DROP VIEW IF EXISTS ${path} CASCADE;`;
+
+      case 'materializedView':
+        return `DROP MATERIALIZED VIEW IF EXISTS ${path} CASCADE;`;
+
+      case 'function':
+      case 'procedure':
+        const fnArgs = change.after?.argumentTypes 
+          ? `(${change.after.argumentTypes.join(', ')})`
+          : '';
+        return `DROP ${objectType === 'procedure' ? 'PROCEDURE' : 'FUNCTION'} IF EXISTS ${path}${fnArgs} CASCADE;`;
+
+      case 'trigger':
+        const trigTable = change.after?.tableName || change.after?.table;
+        const trigName = change.after?.name || change.name;
+        return `DROP TRIGGER IF EXISTS ${trigName} ON ${trigTable};`;
+
+      case 'policy':
+        const polTable = change.after?.table;
+        const polName = change.after?.name || change.name;
+        return `DROP POLICY IF EXISTS ${polName} ON ${polTable};`;
+
+      case 'type':
+        return `DROP TYPE IF EXISTS ${path} CASCADE;`;
+
+      case 'sequence':
+        return `DROP SEQUENCE IF EXISTS ${path} CASCADE;`;
+
+      case 'schema':
+        return `DROP SCHEMA IF EXISTS ${change.after?.name || change.name} CASCADE;`;
+
+      case 'extension':
+        return `DROP EXTENSION IF EXISTS ${change.after?.name || change.name} CASCADE;`;
+
+      case 'rule':
+        const ruleTable = change.after?.tableName || change.after?.table;
+        const ruleName = change.after?.name || change.name;
+        return `DROP RULE IF EXISTS ${ruleName} ON ${ruleTable};`;
+
+      default:
+        return `-- CANNOT AUTO-ROLLBACK: CREATE for object type "${objectType}" on ${path}`;
+    }
+  }
+
+  /**
+   * Generate undo for DROP operations
+   */
+  generateUndoForDrop(change, objectType, path) {
+    switch (objectType) {
+      case 'table':
+        return `-- CANNOT ROLLBACK: Table ${path} was dropped. Data cannot be recovered.`;
+
+      case 'column':
+        return `-- CANNOT FULLY ROLLBACK: Column ${path} was dropped. Data cannot be recovered.`;
+
+      case 'constraint':
+        return `-- CANNOT ROLLBACK: Constraint ${path} was dropped. Recreate manually with original definition.`;
+
+      case 'index':
+        return `-- CANNOT ROLLBACK: Index ${path} was dropped. Recreate manually with original definition.`;
+
+      case 'view':
+      case 'materializedView':
+        return `-- CANNOT ROLLBACK: ${objectType} ${path} was dropped. Recreate manually.`;
+
+      case 'function':
+      case 'procedure':
+        return `-- CANNOT ROLLBACK: ${objectType} ${path} was dropped. Recreate manually.`;
+
+      case 'trigger':
+      case 'policy':
+      case 'rule':
+        return `-- CANNOT ROLLBACK: ${objectType} ${path} was dropped. Recreate manually.`;
+
+      default:
+        return `-- CANNOT AUTO-ROLLBACK: DROP for object type "${objectType}" on ${path}`;
+    }
+  }
+
+  /**
+   * Generate undo for ALTER operations
+   */
+  generateUndoForAlter(change, objectType, path) {
+    const property = change.property;
+    const currentValue = change.currentValue;
+    const desiredValue = change.desiredValue;
+    const parts = path.split('.');
+    const col = parts.pop();
+    const table = parts.join('.');
+
+    switch (property) {
+      case 'dataType':
+      case 'type':
+        return `ALTER TABLE ${table} ALTER COLUMN "${col}" TYPE ${currentValue};`;
+
+      case 'isNullable':
+      case 'notNull':
+        if (desiredValue === true || desiredValue === false && currentValue === true) {
+          return `ALTER TABLE ${table} ALTER COLUMN "${col}" DROP NOT NULL;`;
+        }
+        return `ALTER TABLE ${table} ALTER COLUMN "${col}" SET NOT NULL;`;
+
+      case 'defaultValue':
+      case 'default':
+        if (desiredValue === null) {
+          return `ALTER TABLE ${table} ALTER COLUMN "${col}" SET DEFAULT ${currentValue};`;
+        }
+        if (currentValue === null) {
+          return `ALTER TABLE ${table} ALTER COLUMN "${col}" DROP DEFAULT;`;
+        }
+        return `ALTER TABLE ${table} ALTER COLUMN "${col}" SET DEFAULT ${currentValue};`;
+
+      case 'comment':
+        if (currentValue) {
+          return `COMMENT ON COLUMN ${path} IS '${currentValue.replace(/'/g, "''")}';`;
+        }
+        return `COMMENT ON COLUMN ${path} IS NULL;`;
+
+      default:
+        return `-- CANNOT AUTO-ROLLBACK: Property "${property}" change on ${path}`;
+    }
+  }
+
+  /**
+   * Generate undo for RENAME operations
+   */
+  generateUndoForRename(change, path) {
+    const oldName = change.oldName || change.before?.name;
+    const newName = change.newName || change.after?.name;
+    const objectType = change.objectType;
+    const schema = change.schema;
+
+    switch (objectType) {
+      case 'table':
+        return `ALTER TABLE ${schema}.${newName} RENAME TO ${oldName};`;
+
+      case 'column':
+        const tableName = change.tableName || change.after?.tableName;
+        return `ALTER TABLE ${schema}.${tableName} RENAME COLUMN ${newName} TO ${oldName};`;
+
+      case 'index':
+        return `ALTER INDEX ${schema}.${newName} RENAME TO ${oldName};`;
+
+      case 'constraint':
+        const conTable = change.tableName || change.after?.tableName;
+        return `ALTER TABLE ${schema}.${conTable} RENAME CONSTRAINT ${newName} TO ${oldName};`;
+
+      default:
+        return `-- CANNOT AUTO-ROLLBACK: RENAME for object type "${objectType}" on ${path}`;
+    }
+  }
+
+  /**
+   * Generate undo for REPLACE/RECREATE operations
+   */
+  generateUndoForReplace(change, objectType, path) {
+    const currentValue = change.currentValue || change.before;
+    const before = change.before;
+
+    switch (objectType) {
+      case 'view':
+        if (currentValue?.definition || before?.definition) {
+          return `CREATE OR REPLACE VIEW ${path} AS ${currentValue?.definition || before.definition};`;
+        }
+        return `-- CANNOT ROLLBACK: View ${path} was replaced. Original definition not available.`;
+
+      case 'materializedView':
+        return `-- CANNOT FULLY ROLLBACK: Materialized view ${path} was recreated. Data would need to be refreshed.`;
+
+      case 'function':
+      case 'procedure':
+        if (currentValue?.source || before?.source) {
+          return `CREATE OR REPLACE ${objectType === 'procedure' ? 'PROCEDURE' : 'FUNCTION'} ${path} AS $$${currentValue?.source || before.source}$$;`;
+        }
+        return `-- CANNOT ROLLBACK: ${objectType} ${path} was replaced. Original source not available.`;
+
+      case 'trigger':
+        const trigTable = change.tableName || before?.tableName;
+        const trigName = change.name || before?.name;
+        return `DROP TRIGGER IF EXISTS ${trigName} ON ${trigTable};`;
+
+      case 'policy':
+        return `-- CANNOT FULLY ROLLBACK: Policy ${path} was recreated. May need manual restoration.`;
+
+      default:
+        return `-- CANNOT AUTO-ROLLBACK: REPLACE for object type "${objectType}" on ${path}`;
+    }
+  }
+
+  /**
+   * Check if rollback is possible for a change
+   * @param {Object} change
+   * @returns {{possible: boolean, reason: string}}
+   */
+  canRollback(change) {
+    const changeType = change.changeType;
+    const objectType = change.objectType;
+
+    if (changeType?.startsWith('DROP')) {
+      if (objectType === 'table' || objectType === 'column') {
+        return { possible: false, reason: 'Data loss - cannot recover dropped data' };
+      }
+      return { possible: false, reason: 'Definition lost - need original DDL to recreate' };
+    }
+
+    if (changeType === 'ADD_ENUM_VALUES') {
+      return { possible: false, reason: 'PostgreSQL cannot remove enum values without recreating type' };
+    }
+
+    return { possible: true, reason: 'Rollback available' };
+  }
+
+  /**
+   * Generate full rollback script with comments
+   * @param {Object} migration
+   * @returns {string}
+   */
+  generateRollbackScript(migration) {
+    const steps = this.generateRollback(migration);
+    const lines = [];
+
+    lines.push(`-- Rollback script for migration: ${migration.migration_id || migration.id}`);
+    lines.push(`-- Generated at: ${new Date().toISOString()}`);
+    lines.push(`-- WARNING: This is a best-effort rollback. Some changes cannot be reversed.`);
+    lines.push('');
+    lines.push('BEGIN;');
+    lines.push('');
+
+    for (const step of steps) {
+      if (step.sql.startsWith('--')) {
+        lines.push(`-- Step ${step.originalChangeId}: (cannot rollback)`);
+        lines.push(`-- ${step.sql.replace(/^-- /, '')}`);
+      } else {
+        lines.push(`-- Rollback step ${step.originalChangeId}: ${step.changeType} ${step.objectKey}`);
+        lines.push(step.sql);
+      }
+      lines.push('');
+    }
+
+    lines.push('COMMIT;');
+    lines.push('');
+    lines.push('-- End of rollback script');
+
+    return lines.join('\n');
+  }
+}

package/src/types/changes.js

@@ -0,0 +1,136 @@
+/**
+ * @typedef {'CREATE'|'DROP'|'ALTER'|'RENAME'|'COMMENT'|'ADD_COLUMN'|'DROP_COLUMN'|'ALTER_COLUMN'|'ADD_CONSTRAINT'|'DROP_CONSTRAINT'|'ALTER_CONSTRAINT'|'ADD_INDEX'|'DROP_INDEX'|'ADD_TRIGGER'|'DROP_TRIGGER'|'ADD_POLICY'|'DROP_POLICY'|'ADD_EXTENSION'|'DROP_EXTENSION'|'ADD_FUNCTION'|'DROP_FUNCTION'|'ALTER_FUNCTION'|'ADD_VIEW'|'DROP_VIEW'|'ALTER_VIEW'|'ADD_TYPE'|'DROP_TYPE'|'ALTER_TYPE'|'ADD_SEQUENCE'|'DROP_SEQUENCE'|'ALTER_SEQUENCE'|'ADD_SCHEMA'|'DROP_SCHEMA'|'GRANT'|'REVOKE'|'IMPOSSIBLE_CAST'|'UNSAFE_CAST'|'NARROWING_CAST'|'SAFE_CAST'|'RECREATE_MATERIALIZED_VIEW'|'ADD_ENUM_VALUES'|'REMOVE_ENUM_VALUES'} ChangeType
+ */
+
+/**
+ * @typedef {'none'|'low'|'medium'|'high'|'critical'} RiskLevel
+ */
+
+/**
+ * @typedef {Object} RiskInfo
+ * @property {RiskLevel} level
+ * @property {string[]} categories - e.g., ['data_loss', 'lock_hazard']
+ * @property {string[]} warnings
+ * @property {boolean} safePatternAvailable
+ * @property {boolean} requiresDowntime
+ * @property {string|null} estimatedDuration
+ */
+
+/**
+ * @typedef {Object} ChangeWarning
+ * @property {string} code
+ * @property {string} message
+ * @property {string} [changeKey]
+ * @property {'info'|'warning'|'high'|'critical'} severity
+ * @property {string} [reason]
+ * @property {string[]} [suggestions]
+ */
+
+/**
+ * @typedef {Object} SchemaChange
+ * @property {string} id - Unique change ID
+ * @property {ChangeType} changeType - Type of change
+ * @property {string} objectType - Object type (table, column, index, etc.)
+ * @property {string} objectKey - Fully qualified key (e.g., "public.users.email")
+ * @property {string} [schema] - Schema name
+ * @property {string} [name] - Object name
+ * @property {string} [property] - Property being changed (for ALTERs)
+ * @property {*} [before] - Current value
+ * @property {*} [after] - Desired value
+ * @property {*} [currentValue] - Current property value (property-level diff)
+ * @property {*} [desiredValue] - Desired property value (property-level diff)
+ * @property {number} track - 1 = structural, 2 = behavioral
+ * @property {number} phase - Execution phase (1-25)
+ * @property {string} ddlStrategy - How to generate DDL (CREATE, ALTER, DROP, etc.)
+ * @property {string[]} dependencies - ObjectKeys this change depends on
+ * @property {string[]} dependents - ObjectKeys that depend on this change
+ * @property {RiskInfo} risk - Risk assessment
+ * @property {boolean} [isNonTransactional] - Cannot run in transaction
+ * @property {boolean} [requiresRecreation] - Object must be dropped and recreated
+ * @property {boolean} [safePatternAvailable] - Has a non-blocking alternative
+ * @property {number|null} [pgVersionMinimum] - Minimum PG version (e.g., 14 means PG 14+)
+ * @property {boolean} [dataLossRisk] - This change may lose data
+ * @property {string[]} [collateralDamage] - Other objects affected
+ * @property {boolean} [isRename] - Is a rename change
+ * @property {string} [renameFrom] - Original name if rename
+ * @property {string} [renameTo] - New name if rename
+ * @property {number} [confidence] - Rename detection confidence (0-1)
+ * @property {boolean} [confirmed] - Rename confirmed by user
+ * @property {string} [sql] - Generated SQL (filled by DDL generator)
+ * @property {Record<string,*>} [metadata] - Additional metadata
+ */
+
+/**
+ * @typedef {Object} ObjectMatch
+ * @property {string} objectType
+ * @property {string} key
+ * @property {*} [object] - The object definition
+ * @property {*} [desired] - Desired snapshot object
+ * @property {*} [current] - Current snapshot object
+ * @property {number} [similarity] - Match similarity score
+ */
+
+/**
+ * @typedef {Object} RenameMatch
+ * @property {string} objectType
+ * @property {string} key
+ * @property {string} oldName
+ * @property {string} newName
+ * @property {number} confidence - 0-1
+ * @property {boolean} confirmed - Was rename confirmed by user?
+ * @property {*} [object]
+ */
+
+/**
+ * @typedef {Object} MatchedObjects
+ * @property {ObjectMatch[]} creates - Objects only in desired
+ * @property {ObjectMatch[]} drops - Objects only in current
+ * @property {ObjectMatch[]} matches - Objects in both (property diff needed)
+ * @property {RenameMatch[]} renames - Detected renames (unconfirmed)
+ */
+
+/**
+ * @typedef {Object} DependencyNode
+ * @property {string} key
+ * @property {string} objectType
+ * @property {string[]} dependencies
+ * @property {string[]} dependents
+ */
+
+/**
+ * @typedef {Object} DependencyGraph
+ * @property {Map<string, DependencyNode>} nodes
+ * @property {string[][]} cycles - Detected cycles
+ */
+
+/**
+ * @typedef {Object} ChangeSummary
+ * @property {number} totalChanges
+ * @property {number} creates
+ * @property {number} drops
+ * @property {number} alters
+ * @property {number} renames
+ * @property {number} recreates
+ * @property {number} replaces
+ * @property {Object} byTrack
+ * @property {Object} byPhase
+ * @property {Object} byObjectType
+ * @property {Object} riskSummary
+ * @property {boolean} requiresDowntime
+ * @property {string} estimatedDuration
+ */
+
+/**
+ * @typedef {Object} SchemaDiff
+ * @property {ChangeSummary} summary
+ * @property {SchemaChange[]} changes
+ * @property {ChangeWarning[]} warnings
+ * @property {DependencyGraph} dependencyGraph
+ * @property {Object} metadata
+ * @property {number} metadata.diffDuration
+ * @property {number} metadata.pgVersion
+ * @property {string} [metadata.desiredChecksum]
+ * @property {string} [metadata.currentChecksum]
+ */
+
+export {};

package/src/types/connection.js

@@ -0,0 +1,17 @@
+/**
+ * @typedef {Object} ConnectionConfig
+ * @property {string} host
+ * @property {number} port
+ * @property {string} database
+ * @property {string} user
+ * @property {string} password
+ * @property {boolean|{ca:string,cert:string,key:string}} [ssl]
+ * @property {string[]} [schema]
+ * @property {Record<string,string>} [options]
+ */
+
+/**
+ * @typedef {ConnectionConfig & {maxConnections?:number,idleTimeoutMs?:number,connectionTimeoutMs?:number}} PoolConfig
+ */
+
+export {};

package/src/types/execution.js

@@ -0,0 +1,107 @@
+/**
+ * @typedef {Object} ExecutionOptions
+ * @property {boolean} [dryRun]
+ * @property {boolean} [force]
+ * @property {number} [statementTimeoutMs]
+ * @property {number} [batchSize]
+ * @property {number} [sleepMs]
+ * @property {function(string, string):void} [onProgress]
+ * @property {string} [resumeFrom]
+ */
+
+/**
+ * @typedef {Object} PlanOptions
+ * @property {string} [name]
+ * @property {string} [description]
+ * @property {string} sourceChecksum
+ * @property {string} targetChecksum
+ * @property {boolean} [safeMode]
+ * @property {number} [batchSize]
+ * @property {number} [sleepMs]
+ */
+
+/**
+ * @typedef {Object} MigrationOptions
+ * @property {string} [name]
+ * @property {boolean} [dryRun]
+ * @property {boolean} [force]
+ * @property {boolean} [safeMode]
+ * @property {number} [statementTimeoutMs]
+ * @property {number} [batchSize]
+ * @property {number} [sleepMs]
+ * @property {function(string, string):void} [onProgress]
+ */
+
+/**
+ * @typedef {Object} DdlOptions
+ * @property {number} [pgVersion]
+ * @property {boolean} [safeMode]
+ * @property {boolean} [includeComments]
+ * @property {boolean} [includeGrants]
+ */
+
+/**
+ * @typedef {Object} DriftResult
+ * @property {boolean} hasDrift
+ * @property {import('./changes.js').SchemaChange[]} changes
+ * @property {string} [resolution]
+ */
+
+/**
+ * @typedef {Object} RecoveryResult
+ * @property {string} action
+ * @property {string} message
+ */
+
+/**
+ * @typedef {Object} MigrationRecord
+ * @property {string} id
+ * @property {string} name
+ * @property {string} checksum
+ * @property {'PENDING'|'RUNNING'|'COMPLETED'|'FAILED'|'STALE'} status
+ * @property {MigrationPlan} plan
+ * @property {MigrationResult} [result]
+ * @property {string} [snapshotBefore]
+ * @property {string} [snapshotAfter]
+ * @property {string} [appliedAt]
+ * @property {string} [appliedBy]
+ * @property {number} [durationMs]
+ * @property {string} createdAt
+ */
+
+/**
+ * @typedef {Object} EngineConfig
+ * @property {import('./connection.js').PoolConfig} connection
+ * @property {StorageProvider} [storage]
+ * @property {boolean} [safeMode]
+ * @property {number} [defaultBatchSize]
+ * @property {number} [defaultSleepMs]
+ * @property {number} [statementTimeoutMs]
+ */
+
+/**
+ * @typedef {Object} BackfillOptions
+ * @property {string} table
+ * @property {string} fromColumn
+ * @property {string} toColumn
+ * @property {string} transform
+ * @property {number} batchSize
+ * @property {number} rateLimitMs
+ * @property {string} pkColumn
+ */
+
+/**
+ * @typedef {Object} StorageProvider
+ * @property {function(string, import('./schema.js').SchemaModel):Promise<void>} saveSnapshot
+ * @property {function(string):Promise<import('./schema.js').SchemaModel>} loadSnapshot
+ * @property {function():Promise<Array<{checksum:string,timestamp:string}>>} listSnapshots
+ * @property {function(MigrationRecord):Promise<void>} saveMigration
+ * @property {function(string):Promise<MigrationRecord|null>} getMigration
+ * @property {function():Promise<MigrationRecord|null>} getLatestMigration
+ * @property {function():Promise<MigrationRecord[]>} getMigrationHistory
+ * @property {function(string,string):Promise<void>} saveMigrationFile
+ * @property {function(string):Promise<string>} loadMigrationFile
+ * @property {function():Promise<string[]>} listMigrationFiles
+ */
+
+export {};

package/src/types/index.js

@@ -0,0 +1 @@
+export {};

package/src/types/migration.js

@@ -0,0 +1,67 @@
+/**
+ * @typedef {Object} MigrationPlan
+ * @property {string} id
+ * @property {string} name
+ * @property {string} [description]
+ * @property {string} createdAt
+ * @property {string} sourceChecksum
+ * @property {string} targetChecksum
+ * @property {import('./changes.js').SchemaChange[]} changes
+ * @property {MigrationStep[]} steps
+ * @property {import('./risk.js').RiskAssessment} riskAssessment
+ * @property {number} [estimatedDurationMs]
+ * @property {boolean} isReversible
+ * @property {MigrationPlan} [reversePlan]
+ */
+
+/**
+ * @typedef {'pre_check'|'advisory_lock'|'pre_structural'|'structural'|'index'|'data_migration'|'constraint'|'post_structural'|'policy'|'grant'|'cleanup'|'snapshot'|'verify'} StepType
+ */
+
+/**
+ * @typedef {Object} MigrationStep
+ * @property {string} id
+ * @property {StepType} type
+ * @property {number} phase
+ * @property {string} description
+ * @property {string} sql
+ * @property {boolean} isTransactional
+ * @property {number} [timeoutMs]
+ * @property {number} [retryCount]
+ * @property {import('./risk.js').RiskLevel} riskLevel
+ * @property {string[]} dependencies
+ * @property {number} [estimatedRows]
+ */
+
+/**
+ * @typedef {Object} MigrationResult
+ * @property {boolean} success
+ * @property {string} migrationId
+ * @property {number} stepsCompleted
+ * @property {number} stepsTotal
+ * @property {number} durationMs
+ * @property {number} changesApplied
+ * @property {MigrationWarning[]} warnings
+ * @property {MigrationError[]} errors
+ * @property {string} [snapshotBefore]
+ * @property {string} [snapshotAfter]
+ */
+
+/**
+ * @typedef {Object} MigrationWarning
+ * @property {string} step
+ * @property {string} message
+ * @property {import('./risk.js').RiskLevel} severity
+ */
+
+/**
+ * @typedef {Object} MigrationError
+ * @property {string} step
+ * @property {string} message
+ * @property {string} sql
+ * @property {string} [code]
+ * @property {boolean} isRecoverable
+ * @property {string} [recoveryHint]
+ */
+
+export {};