pg-migration-engine 0.1.0

package/src/introspection/version-detector.js

@@ -0,0 +1,25 @@
+/**
+ * @param {import('pg').Pool} pool
+ * @returns {Promise<number>}
+ */
+export async function detectPgVersion(pool) {
+  const result = await pool.query("SELECT current_setting('server_version_num')::int AS version_num");
+  return result.rows[0].version_num;
+}
+
+/**
+ * @param {import('pg').Pool} pool
+ * @returns {Promise<string>}
+ */
+export async function detectPgVersionString(pool) {
+  const result = await pool.query("SELECT current_setting('server_version') AS version");
+  return result.rows[0].version;
+}
+
+/**
+ * @param {number} versionNum
+ * @returns {number}
+ */
+export function majorVersion(versionNum) {
+  return Math.floor(versionNum / 10000);
+}

package/src/planner/backfill-planner.js

@@ -0,0 +1,36 @@
+export class BackfillPlanner {
+  /**
+   * @param {import('../types/execution.js').BackfillOptions} options
+   * @returns {import('../types/migration.js').MigrationStep[]}
+   */
+  createBackfillPlan(options) {
+    const { table, fromColumn, toColumn, transform, batchSize = 5000, rateLimitMs = 50, pkColumn = 'id' } = options;
+    const steps = [];
+
+    steps.push({
+      id: `backfill_${Date.now()}_1`,
+      type: 'data_migration',
+      phase: 5,
+      description: `Create sync trigger for ${table}`,
+      sql: `-- Sync trigger: keep ${fromColumn} and ${toColumn} in sync during backfill`,
+      isTransactional: true,
+      riskLevel: 'low',
+      dependencies: [],
+    });
+
+    steps.push({
+      id: `backfill_${Date.now()}_2`,
+      type: 'data_migration',
+      phase: 5,
+      description: `Batched backfill: ${table}.${fromColumn} -> ${toColumn}`,
+      sql: `-- Batched backfill: UPDATE ${table} SET ${toColumn} = ${transform} WHERE ${pkColumn} BETWEEN ? AND ? AND ${toColumn} IS NULL;`,
+      isTransactional: true,
+      riskLevel: 'medium',
+      dependencies: [`backfill_${Date.now()}_1`],
+      estimatedRows: 100000,
+      metadata: { batchSize, rateLimitMs },
+    });
+
+    return steps;
+  }
+}

package/src/planner/dry-run.js

@@ -0,0 +1,21 @@
+export class DryRun {
+  /**
+   * @param {import('pg').Pool} pool
+   * @param {import('../types/migration.js').MigrationStep} step
+   * @returns {Promise<{success: boolean, error?: string}>}
+   */
+  async execute(pool, step) {
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query(step.sql);
+      await client.query('ROLLBACK');
+      return { success: true };
+    } catch (error) {
+      await client.query('ROLLBACK');
+      return { success: false, error: error.message };
+    } finally {
+      client.release();
+    }
+  }
+}

package/src/planner/index.js

@@ -0,0 +1,6 @@
+export { MigrationPlanner } from './migration-planner.js';
+export { SmartMigrator } from './smart-migrator.js';
+export { BackfillPlanner } from './backfill-planner.js';
+export { StepSequencer } from './step-sequencer.js';
+export { TypeRegistry } from './type-registry.js';
+export { DryRun } from './dry-run.js';

package/src/planner/migration-planner.js

@@ -0,0 +1,356 @@
+import { SmartMigrator } from './smart-migrator.js';
+import { BackfillPlanner } from './backfill-planner.js';
+import { StepSequencer } from './step-sequencer.js';
+
+const DROP_PHASES = {
+  behavioral: 27,
+  constraints: 28,
+  indexes: 29,
+  columns: 30,
+  sequences: 31,
+  structural: 32,
+};
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export class MigrationPlanner {
+  constructor() {
+    this.smartMigrator = new SmartMigrator();
+    this.backfillPlanner = new BackfillPlanner();
+    this.sequencer = new StepSequencer();
+  }
+
+  correlateRenames(changes) {
+    const renameMap = new Map();
+    for (const change of changes) {
+      if (change.changeType === 'RENAME') {
+        const oldKey = change.objectKey;
+        const schema = change.schema || oldKey.split('.')[0] || 'public';
+        const renameTo = change.renameTo || change.after?.name;
+        if (renameTo) {
+          const newKey = this.buildObjectKey(change.objectType, renameTo, schema);
+          renameMap.set(oldKey, {
+            newKey,
+            renameChange: change,
+            objectType: change.objectType,
+            oldName: change.before?.name || oldKey.split('.').pop(),
+            newName: renameTo,
+          });
+        }
+      }
+    }
+    for (const [oldKey, renameInfo] of renameMap) {
+      for (const [otherOldKey, otherRenameInfo] of renameMap) {
+        if (renameInfo.newKey === otherOldKey && oldKey !== otherOldKey) {
+          const secondRename = otherRenameInfo.renameChange;
+          const firstRename = renameInfo.renameChange;
+          if (!secondRename.dependencies) secondRename.dependencies = [];
+          if (firstRename.id && !secondRename.dependencies.includes(firstRename.id)) {
+            secondRename.dependencies.push(firstRename.id);
+          }
+        }
+      }
+    }
+    for (const change of changes) {
+      const changeType = change.changeType?.toUpperCase();
+      if (changeType === 'ALTER') {
+        for (const [oldKey, renameInfo] of renameMap) {
+          if (change.objectKey === renameInfo.newKey) {
+            if (!change.dependencies) change.dependencies = [];
+            const renameId = renameInfo.renameChange.id;
+            if (renameId && !change.dependencies.includes(renameId)) {
+              change.dependencies.push(renameId);
+            }
+          }
+        }
+      }
+    }
+    for (const change of changes) {
+      if (change.changeType === 'RENAME' && change.objectType === 'column') {
+        const renameInfo = renameMap.get(change.objectKey);
+        if (renameInfo) {
+          const tableKey = change.objectKey.substring(0, change.objectKey.lastIndexOf('.'));
+          const oldColName = renameInfo.oldName;
+          const newColName = renameInfo.newName;
+          if (oldColName && newColName) {
+            const newColumnKey = `${tableKey}.${newColName}`;
+            for (const alterChange of changes) {
+              const alterChangeType = alterChange.changeType?.toUpperCase();
+              if (alterChangeType === 'ALTER' && alterChange.objectKey === newColumnKey) {
+                if (!alterChange.dependencies) alterChange.dependencies = [];
+                const renameId = change.id;
+                if (renameId && !alterChange.dependencies.includes(renameId)) {
+                  alterChange.dependencies.push(renameId);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  buildObjectKey(objectType, name, schema) {
+    return `${schema}.${name}`;
+  }
+
+  /**
+   * @param {import('../types/changes.js').SchemaChange[]|import('../types/changes.js').SchemaDiff} changes
+   * @param {import('../types/execution.js').PlanOptions} options
+   * @returns {import('../types/migration.js').MigrationPlan}
+   */
+  createPlan(changes, options) {
+    const changesArray = Array.isArray(changes) ? changes : (changes.changes || []);
+    const warnings = Array.isArray(changes) ? [] : (changes.warnings || []);
+
+    this.correlateRenames(changesArray);
+    
+    const steps = [];
+    let stepId = 1;
+
+    steps.push({
+      id: `step_${String(stepId++).padStart(3, '0')}`,
+      type: 'pre_check',
+      phase: 0,
+      description: 'Pre-flight validation',
+      sql: 'SELECT 1;',
+      isTransactional: true,
+      riskLevel: 'none',
+      dependencies: [],
+    });
+
+    steps.push({
+      id: `step_${String(stepId++).padStart(3, '0')}`,
+      type: 'advisory_lock',
+      phase: 0,
+      description: 'Acquire migration advisory lock',
+      sql: 'SELECT pg_try_advisory_xact_lock(12345);',
+      isTransactional: true,
+      riskLevel: 'none',
+      dependencies: [`step_001`],
+    });
+
+    const phases = {};
+    for (const change of changesArray) {
+      const phase = change.phase || this.mapChangeToPhase(change);
+      if (!phases[phase]) phases[phase] = [];
+      phases[phase].push(change);
+    }
+
+    const phaseOrder = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32];
+    
+    for (const phaseNum of phaseOrder) {
+      const phaseChanges = phases[phaseNum] || [];
+      for (const change of phaseChanges) {
+        const smartSteps = this.smartMigrator.analyze(change);
+        const changeId = change.id || `change_${stepId}`;
+        
+        if (smartSteps) {
+          for (const s of smartSteps) {
+            s.id = `step_${String(stepId++).padStart(3, '0')}`;
+            s.phase = phaseNum;
+            s.changeId = changeId;
+            steps.push(s);
+          }
+        } else {
+          const isConcurrentIndex = change.objectType === 'index' && 
+                                    change.changeType === 'CREATE' && 
+                                    (change.isConcurrent || change.isNonTransactional || phaseNum === 23);
+          
+          if (isConcurrentIndex) {
+            const indexName = change.after?.name || change.name || change.objectKey?.split('.').pop();
+            const tableName = change.after?.table || change.tableName;
+            const schema = change.schema || change.objectKey?.split('.')[0] || 'public';
+            
+            steps.push({
+              id: `step_${String(stepId++).padStart(3, '0')}`,
+              type: 'pre_check',
+              phase: 22,
+              changeId,
+              description: `Pre-check: Verify index ${indexName} does not already exist`,
+              sql: `SELECT 1 FROM pg_indexes WHERE indexname = '${indexName}' AND schemaname = '${schema}'${tableName ? ` AND tablename = '${tableName}'` : ''}`,
+              isTransactional: true,
+              riskLevel: 'none',
+              dependencies: [],
+              preCheck: true,
+              preCheckExpectEmpty: true,
+              preCheckMessage: `Index ${indexName} already exists`,
+            });
+          }
+          
+          const step = {
+            id: `step_${String(stepId++).padStart(3, '0')}`,
+            type: this.mapChangeToStepType(change),
+            phase: phaseNum,
+            changeId,
+            description: `${change.changeType} ${change.objectType} ${change.objectKey}`,
+            sql: change.sql || `-- ${change.changeType} ${change.objectType} ${change.objectKey}`,
+            isTransactional: change.isNonTransactional !== true,
+            riskLevel: change.risk?.level || 'none',
+            dependencies: (change.dependencies || []).map(d => `change_${d}`),
+            track: change.track,
+          };
+          
+          if (isConcurrentIndex) {
+            const indexName = change.after?.name || change.name || change.objectKey?.split('.').pop();
+            const schema = change.schema || change.objectKey?.split('.')[0] || 'public';
+            step.recoverySql = `DROP INDEX IF EXISTS ${schema}.${indexName}`;
+          }
+          
+          steps.push(step);
+        }
+      }
+    }
+
+    steps.push({
+      id: `step_${String(stepId++).padStart(3, '0')}`,
+      type: 'snapshot',
+      phase: 26,
+      description: 'Capture post-migration snapshot',
+      sql: '-- Snapshot capture',
+      isTransactional: false,
+      riskLevel: 'none',
+      dependencies: [`step_${String(stepId - 2).padStart(3, '0')}`],
+    });
+
+    steps.push({
+      id: `step_${String(stepId++).padStart(3, '0')}`,
+      type: 'verify',
+      phase: 26,
+      description: 'Post-migration verification',
+      sql: '-- Verify schema matches target',
+      isTransactional: false,
+      riskLevel: 'none',
+      dependencies: [`step_${String(stepId - 2).padStart(3, '0')}`],
+    });
+
+    const sequencedSteps = this.sequencer.sequence(changesArray, steps);
+    const summary = Array.isArray(changes) ? this.buildSummary(changes) : changes.summary;
+
+    return {
+      id: `migration_${Date.now()}`,
+      name: options.name || `migration_${Date.now()}`,
+      description: options.description,
+      createdAt: new Date().toISOString(),
+      sourceChecksum: options.sourceChecksum,
+      targetChecksum: options.targetChecksum,
+      changes: changesArray,
+      warnings,
+      steps: sequencedSteps,
+      riskAssessment: {
+        overallRisk: summary?.riskSummary ? this.getOverallRisk(summary.riskSummary) : 'none',
+        findings: [],
+        destructiveChanges: summary?.riskSummary?.categories?.data_loss || 0,
+        dataLossChanges: summary?.riskSummary?.categories?.data_loss || 0,
+        lockRiskChanges: summary?.riskSummary?.categories?.lock_hazard || 0,
+        canAutoFix: Array.isArray(summary?.riskSummary?.categories) 
+          ? summary.riskSummary.categories.map(c => c.safePatternAvailable).filter(Boolean).length 
+          : 0,
+        requiresReview: summary?.riskSummary?.categories?.rename_unconfirmed || 0,
+        estimatedDowntime: summary?.requiresDowntime ? 'POTENTIAL' : 'NONE',
+      },
+      isReversible: this.checkReversibility(changesArray),
+      summary,
+    };
+  }
+
+  buildSummary(changes) {
+    return {
+      totalChanges: changes.length,
+      creates: changes.filter(c => c.changeType === 'CREATE').length,
+      drops: changes.filter(c => c.changeType === 'DROP').length,
+      alters: changes.filter(c => c.changeType === 'ALTER').length,
+      renames: changes.filter(c => c.changeType === 'RENAME').length,
+    };
+  }
+
+  getOverallRisk(riskSummary) {
+    if (riskSummary.critical > 0) return 'critical';
+    if (riskSummary.high > 0) return 'high';
+    if (riskSummary.medium > 0) return 'medium';
+    if (riskSummary.low > 0) return 'low';
+    return 'none';
+  }
+
+  mapChangeToStepType(change) {
+    const objType = change.objectType;
+    if (objType === 'index') return 'index';
+    if (objType === 'constraint') return 'constraint';
+    if (objType === 'trigger') return 'post_structural';
+    if (objType === 'policy') return 'policy';
+    if (objType === 'view' || objType === 'materializedView') return 'view';
+    if (objType === 'function' || objType === 'procedure') return 'function';
+    return 'structural';
+  }
+
+  mapChangeToPhase(change) {
+    const objType = change.objectType;
+    const changeType = change.changeType?.toUpperCase();
+    
+    if (changeType === 'DROP' || changeType?.startsWith('REMOVE')) {
+      if (['trigger', 'policy', 'rule', 'eventTrigger'].includes(objType)) return DROP_PHASES.behavioral;
+      if (['view', 'materializedView'].includes(objType)) return DROP_PHASES.behavioral;
+      if (['function', 'procedure', 'aggregate'].includes(objType)) return DROP_PHASES.behavioral;
+      if (['textSearchConfig', 'textSearchDict', 'textSearchParser', 'textSearchTemplate'].includes(objType)) return DROP_PHASES.behavioral;
+      if (['conversion', 'language'].includes(objType)) return DROP_PHASES.behavioral;
+      if (['foreignDataWrapper', 'foreignServer', 'userMapping'].includes(objType)) return DROP_PHASES.behavioral;
+      if (['publication', 'subscription'].includes(objType)) return DROP_PHASES.behavioral;
+      
+      if (objType === 'constraint') return DROP_PHASES.constraints;
+      
+      if (objType === 'index') return DROP_PHASES.indexes;
+      
+      if (objType === 'column') return DROP_PHASES.columns;
+      
+      if (objType === 'sequence') return DROP_PHASES.sequences;
+      
+      if (['table', 'foreignTable'].includes(objType)) return DROP_PHASES.structural;
+      if (['type', 'collation', 'operator', 'operatorClass', 'operatorFamily', 'cast'].includes(objType)) return DROP_PHASES.structural;
+      if (['extension', 'schema', 'accessMethod', 'defaultPrivileges'].includes(objType)) return DROP_PHASES.structural;
+      if (['statistics'].includes(objType)) return DROP_PHASES.structural;
+      
+      return DROP_PHASES.behavioral;
+    }
+    
+    if (changeType === 'CREATE' || changeType?.startsWith('ADD')) {
+      if (objType === 'extension') return 3;
+      if (objType === 'schema') return 5;
+      if (objType === 'type') return 4;
+      if (objType === 'table') return 6;
+      if (objType === 'foreignTable') return 6;
+      if (objType === 'column') return 7;
+      if (objType === 'sequence') return 8;
+      if (objType === 'index') return change.isNonTransactional || change.isConcurrent ? 23 : 9;
+      if (objType === 'constraint' && change.constraintType !== 'FOREIGN_KEY') return 10;
+      if (objType === 'view') return 14;
+      if (objType === 'materializedView') return 15;
+      if (objType === 'function' || objType === 'procedure') return 16;
+      if (objType === 'trigger') return 17;
+      if (objType === 'eventTrigger') return 17;
+      if (objType === 'policy') return 18;
+      if (objType === 'rule') return 19;
+      if (objType === 'operator') return 20;
+      if (objType === 'operatorClass') return 20;
+      if (objType === 'operatorFamily') return 20;
+      return 10;
+    }
+    
+    if (changeType === 'ALTER') {
+      if (objType === 'column') return 11;
+      if (objType === 'constraint') return change.constraintType === 'FOREIGN_KEY' ? 12 : 10;
+      if (objType === 'function' || objType === 'procedure') return 16;
+      if (objType === 'view') return 14;
+      if (objType === 'sequence') return 8;
+      if (objType === 'policy') return 18;
+      return 20;
+    }
+    
+    return 10;
+  }
+
+  checkReversibility(changes) {
+    return !changes.some(c => c.changeType === 'DROP' && c.objectType === 'table');
+  }
+}

package/src/planner/smart-migrator.js

@@ -0,0 +1,82 @@
+import { TypeRegistry } from './type-registry.js';
+
+const PHASES = {
+  ADD_COLUMN: 7,
+  DATA_MIGRATION: 11,
+  DROP_COLUMN: 30,
+};
+
+export class SmartMigrator {
+  constructor() {
+    this.typeRegistry = new TypeRegistry();
+  }
+
+  /**
+   * @param {import('../types/changes.js').SchemaChange} change
+   * @returns {import('../types/migration.js').MigrationStep[] | null}
+   */
+  analyze(change) {
+    const isAlterColumn = change.changeType === 'ALTER' && 
+                          change.objectType === 'column' && 
+                          change.changedProperties?.includes('dataType');
+    
+    if (!isAlterColumn) return null;
+
+    const fromType = change.before?.dataType;
+    const toType = change.after?.dataType;
+    if (!fromType || !toType) return null;
+
+    if (this.typeRegistry.isImpossibleCast(fromType, toType)) {
+      return this.createMultiStepPlan(change, fromType, toType);
+    }
+
+    return null;
+  }
+
+  /**
+   * @param {import('../types/changes.js').SchemaChange} change
+   * @param {string} fromType
+   * @param {string} toType
+   * @returns {import('../types/migration.js').MigrationStep[]}
+   */
+  createMultiStepPlan(change, fromType, toType) {
+    const table = change.objectKey.split('.').slice(0, -1).join('.');
+    const col = change.after?.name || change.name;
+    const tempCol = `${col}_new`;
+    const stepBase = `smart_${Date.now()}`;
+
+    return [
+      {
+        id: `${stepBase}_1`,
+        type: 'structural',
+        phase: PHASES.ADD_COLUMN,
+        description: `Add new column ${tempCol} with type ${toType}`,
+        sql: `ALTER TABLE ${table} ADD COLUMN ${tempCol} ${toType};`,
+        isTransactional: true,
+        riskLevel: 'low',
+        dependencies: [],
+      },
+      {
+        id: `${stepBase}_2`,
+        type: 'data_migration',
+        phase: PHASES.DATA_MIGRATION,
+        description: `Backfill data from ${col} to ${tempCol}`,
+        sql: `-- Batched backfill: UPDATE ${table} SET ${tempCol} = ${col}::${toType} WHERE ${tempCol} IS NULL;`,
+        isTransactional: true,
+        riskLevel: 'medium',
+        dependencies: [`${stepBase}_1`],
+        estimatedRows: 10000,
+      },
+      {
+        id: `${stepBase}_3`,
+        type: 'structural',
+        phase: PHASES.DROP_COLUMN,
+        description: `Drop old column and rename new column`,
+        sql: `ALTER TABLE ${table} DROP COLUMN ${col}; ALTER TABLE ${table} RENAME COLUMN ${tempCol} TO ${col};`,
+        isTransactional: true,
+        riskLevel: 'high',
+        dependencies: [`${stepBase}_2`],
+      },
+    ];
+  }
+}

package/src/planner/step-sequencer.js

@@ -0,0 +1,61 @@
+export class StepSequencer {
+  /**
+   * @param {import('../types/changes.js').SchemaChange[]} changes
+   * @param {import('../types/migration.js').MigrationStep[]} steps
+   * @returns {import('../types/migration.js').MigrationStep[]}
+   */
+  sequence(changes, steps) {
+    const sequenced = [];
+    const stepMap = new Map(steps.map(s => [s.id, s]));
+
+    const sorted = this.topologicalSort(steps);
+    let idCounter = 1;
+
+    for (const step of sorted) {
+      sequenced.push({
+        ...step,
+        id: `step_${String(idCounter).padStart(3, '0')}`,
+      });
+      idCounter++;
+    }
+
+    return sequenced;
+  }
+
+  /**
+   * @param {import('../types/migration.js').MigrationStep[]} steps
+   * @returns {import('../types/migration.js').MigrationStep[]}
+   */
+  topologicalSort(steps) {
+    const stepMap = new Map(steps.map(s => [s.id, s]));
+    const inDegree = new Map(steps.map(s => [s.id, 0]));
+    const adj = new Map(steps.map(s => [s.id, []]));
+
+    for (const step of steps) {
+      for (const depId of step.dependencies || []) {
+        if (adj.has(depId)) {
+          adj.get(depId).push(step.id);
+          inDegree.set(step.id, (inDegree.get(step.id) || 0) + 1);
+        }
+      }
+    }
+
+    const queue = [];
+    for (const [id, degree] of inDegree) {
+      if (degree === 0) queue.push(id);
+    }
+
+    const sorted = [];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      sorted.push(stepMap.get(current));
+
+      for (const neighbor of adj.get(current) || []) {
+        inDegree.set(neighbor, inDegree.get(neighbor) - 1);
+        if (inDegree.get(neighbor) === 0) queue.push(neighbor);
+      }
+    }
+
+    return sorted;
+  }
+}

package/src/planner/type-registry.js

@@ -0,0 +1,47 @@
+/**
+ * Type cast compatibility matrix
+ */
+export class TypeRegistry {
+  constructor() {
+    this.implicitCasts = new Map([
+      ['smallint', new Set(['integer', 'bigint', 'real', 'double precision', 'numeric', 'decimal'])],
+      ['integer', new Set(['bigint', 'real', 'double precision', 'numeric', 'decimal'])],
+      ['bigint', new Set(['real', 'double precision', 'numeric', 'decimal'])],
+      ['real', new Set(['double precision', 'numeric'])],
+      ['numeric', new Set(['numeric'])],
+      ['character varying', new Set(['text', 'character varying'])],
+      ['character', new Set(['text', 'character varying', 'character'])],
+      ['text', new Set(['character varying'])],
+      ['date', new Set(['timestamp', 'timestamptz'])],
+      ['timestamp', new Set(['timestamptz'])],
+    ]);
+
+    this.impossibleCasts = new Set([
+      'text->integer', 'text->bigint', 'text->numeric',
+      'integer->boolean', 'boolean->integer',
+      'text->date', 'text->timestamp', 'text->uuid',
+      'jsonb->json', 'json->jsonb',
+    ]);
+  }
+
+  canCastImplicitly(from, to) {
+    return this.implicitCasts.get(from.toLowerCase())?.has(to.toLowerCase()) || false;
+  }
+
+  isImpossibleCast(from, to) {
+    return this.impossibleCasts.has(`${from.toLowerCase()}->${to.toLowerCase()}`);
+  }
+
+  requiresUsingClause(from, to) {
+    return !this.canCastImplicitly(from, to) && !this.isImpossibleCast(from, to);
+  }
+
+  generateUsingClause(from, to, column) {
+    if (to.toLowerCase() === 'text' || to.toLowerCase().startsWith('character')) return `${column}::text`;
+    if (to.toLowerCase() === 'integer') return `${column}::integer`;
+    if (to.toLowerCase() === 'numeric') return `${column}::numeric`;
+    if (to.toLowerCase() === 'uuid') return `${column}::uuid`;
+    if (to.toLowerCase() === 'timestamptz') return `${column}::timestamptz`;
+    return `${column}::${to}`;
+  }
+}

package/src/risk/compatibility-checker.js

@@ -0,0 +1,29 @@
+/**
+ * @param {import('../types/changes.js').SchemaChange} change
+ * @param {number} pgVersion
+ * @returns {import('../types/risk.js').RiskFinding[]}
+ */
+export function checkCompatibility(change, pgVersion) {
+  const findings = [];
+  if (pgVersion < 150000 && change.after?.nullsNotDistinct) {
+    findings.push({
+      category: 'compatibility',
+      severity: 'high',
+      changeId: change.id,
+      message: 'NULLS NOT DISTINCT requires PostgreSQL 15+',
+      recommendation: 'Remove NULLS NOT DISTINCT or upgrade PostgreSQL',
+      autoFixable: false,
+    });
+  }
+  if (pgVersion < 180000 && change.after?.generatedStorage === 'VIRTUAL') {
+    findings.push({
+      category: 'compatibility',
+      severity: 'high',
+      changeId: change.id,
+      message: 'VIRTUAL generated columns require PostgreSQL 18+',
+      recommendation: 'Use STORED generated columns or upgrade PostgreSQL',
+      autoFixable: true,
+    });
+  }
+  return findings;
+}