@dotdo/postgres 0.1.0

package/src/migrations/compatibility.ts

@@ -0,0 +1,902 @@
+/**
+ * Schema Compatibility Validator
+ *
+ * Validates schema changes for compatibility before running migrations.
+ * Detects breaking changes, safe changes, and generates compatibility reports.
+ *
+ * @module migrations/compatibility
+ */
+
+import type { TableDefinition, DatabaseSchema, ColumnDefinition } from './schema-generator'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Type of schema change
+ */
+export type SchemaChangeType =
+  | 'TABLE_CREATED'
+  | 'TABLE_DROPPED'
+  | 'TABLE_RENAMED'
+  | 'COLUMN_CREATED'
+  | 'COLUMN_DROPPED'
+  | 'COLUMN_RENAMED'
+  | 'COLUMN_TYPE_CHANGED'
+  | 'COLUMN_NULLABILITY_CHANGED'
+  | 'COLUMN_DEFAULT_ADDED'
+  | 'COLUMN_DEFAULT_REMOVED'
+  | 'COLUMN_DEFAULT_CHANGED'
+  | 'INDEX_CREATED'
+  | 'INDEX_DROPPED'
+  | 'CONSTRAINT_ADDED'
+  | 'CONSTRAINT_DROPPED'
+  | 'FOREIGN_KEY_ADDED'
+  | 'FOREIGN_KEY_DROPPED'
+
+/**
+ * Schema change detected between two schemas
+ */
+export interface SchemaChange {
+  /** Type of change */
+  type: SchemaChangeType
+  /** Table affected */
+  table: string
+  /** Column affected (if applicable) */
+  column?: string
+  /** Old value (if applicable) */
+  oldValue?: unknown
+  /** New value (if applicable) */
+  newValue?: unknown
+  /** Whether this is a breaking change */
+  isBreaking: boolean
+  /** Reason why this is breaking (if applicable) */
+  breakingReason?: string | undefined
+  /** Description of the change */
+  description: string
+  /** Severity of the change */
+  severity: 'low' | 'medium' | 'high'
+  /** Additional metadata */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Compatibility report between two schemas
+ */
+export interface CompatibilityReport {
+  /** Whether the schemas are backward compatible */
+  isBackwardCompatible: boolean
+  /** All detected changes */
+  changes: SchemaChange[]
+  /** Breaking changes only */
+  breakingChanges: SchemaChange[]
+  /** Safe changes only */
+  safeChanges: SchemaChange[]
+  /** Number of breaking changes */
+  breakingChangeCount: number
+  /** Number of safe changes */
+  safeChangeCount: number
+  /** Overall risk level */
+  riskLevel: 'none' | 'low' | 'medium' | 'high'
+  /** Summary message */
+  summary: string
+  /** Recommendations for migration */
+  recommendations: string[]
+}
+
+/**
+ * Options for compatibility validation
+ */
+export interface CompatibilityOptions {
+  /**
+   * Whether to treat column drops as breaking
+   * Default: true
+   */
+  columnDropsAreBreaking?: boolean
+
+  /**
+   * Whether to treat table drops as breaking
+   * Default: true
+   */
+  tableDropsAreBreaking?: boolean
+
+  /**
+   * Whether to treat type changes as breaking
+   * Default: true
+   */
+  typeChangesAreBreaking?: boolean
+
+  /**
+   * Whether adding NOT NULL without default is breaking
+   * Default: true
+   */
+  notNullWithoutDefaultIsBreaking?: boolean
+
+  /**
+   * Whether removing defaults is breaking
+   * Default: false
+   */
+  removingDefaultsIsBreaking?: boolean
+
+  /**
+   * Whether to detect column renames (heuristic based on similar names)
+   * Default: true
+   */
+  detectRenames?: boolean
+}
+
+// ============================================================================
+// Schema Compatibility Validator
+// ============================================================================
+
+/**
+ * Schema Compatibility Validator
+ *
+ * Validates schema changes for compatibility and generates detailed reports.
+ *
+ * @example
+ * ```typescript
+ * const validator = new SchemaCompatibilityValidator()
+ *
+ * const report = validator.validate(oldSchema, newSchema)
+ *
+ * if (!report.isBackwardCompatible) {
+ *   console.log('Breaking changes detected:')
+ *   for (const change of report.breakingChanges) {
+ *     console.log(`- ${change.description}`)
+ *   }
+ * }
+ * ```
+ */
+export class SchemaCompatibilityValidator {
+  private options: Required<CompatibilityOptions>
+
+  constructor(options: CompatibilityOptions = {}) {
+    this.options = {
+      columnDropsAreBreaking: options.columnDropsAreBreaking ?? true,
+      tableDropsAreBreaking: options.tableDropsAreBreaking ?? true,
+      typeChangesAreBreaking: options.typeChangesAreBreaking ?? true,
+      notNullWithoutDefaultIsBreaking: options.notNullWithoutDefaultIsBreaking ?? true,
+      removingDefaultsIsBreaking: options.removingDefaultsIsBreaking ?? false,
+      detectRenames: options.detectRenames ?? true,
+    }
+  }
+
+  /**
+   * Validate compatibility between two schemas
+   */
+  validate(oldSchema: DatabaseSchema, newSchema: DatabaseSchema): CompatibilityReport {
+    const changes: SchemaChange[] = []
+
+    // Detect table changes
+    changes.push(...this.detectTableChanges(oldSchema, newSchema))
+
+    // Detect column changes for existing tables
+    changes.push(...this.detectColumnChanges(oldSchema, newSchema))
+
+    // Detect index changes
+    changes.push(...this.detectIndexChanges(oldSchema, newSchema))
+
+    // Detect foreign key changes
+    changes.push(...this.detectForeignKeyChanges(oldSchema, newSchema))
+
+    // Separate breaking and safe changes
+    const breakingChanges = changes.filter((c) => c.isBreaking)
+    const safeChanges = changes.filter((c) => !c.isBreaking)
+
+    // Determine risk level
+    const riskLevel = this.calculateRiskLevel(breakingChanges)
+
+    // Generate summary
+    const summary = this.generateSummary(changes, breakingChanges, safeChanges)
+
+    // Generate recommendations
+    const recommendations = this.generateRecommendations(breakingChanges)
+
+    return {
+      isBackwardCompatible: breakingChanges.length === 0,
+      changes,
+      breakingChanges,
+      safeChanges,
+      breakingChangeCount: breakingChanges.length,
+      safeChangeCount: safeChanges.length,
+      riskLevel,
+      summary,
+      recommendations,
+    }
+  }
+
+  /**
+   * Check if two schemas are backward compatible
+   */
+  isBackwardCompatible(oldSchema: DatabaseSchema, newSchema: DatabaseSchema): boolean {
+    const report = this.validate(oldSchema, newSchema)
+    return report.isBackwardCompatible
+  }
+
+  /**
+   * Get only safe changes from a compatibility report
+   */
+  getSafeChanges(changes: SchemaChange[]): SchemaChange[] {
+    return changes.filter((c) => !c.isBreaking)
+  }
+
+  /**
+   * Get only breaking changes from a compatibility report
+   */
+  getBreakingChanges(changes: SchemaChange[]): SchemaChange[] {
+    return changes.filter((c) => c.isBreaking)
+  }
+
+  // ============================================================================
+  // Private Methods - Change Detection
+  // ============================================================================
+
+  /**
+   * Detect table-level changes
+   */
+  private detectTableChanges(oldSchema: DatabaseSchema, newSchema: DatabaseSchema): SchemaChange[] {
+    const changes: SchemaChange[] = []
+    const oldTables = new Map(oldSchema.tables.map((t) => [t.name, t]))
+    const newTables = new Map(newSchema.tables.map((t) => [t.name, t]))
+
+    // Check for dropped tables
+    for (const [tableName, oldTable] of oldTables) {
+      if (!newTables.has(tableName)) {
+        // Check if this might be a rename
+        if (this.options.detectRenames) {
+          const possibleRename = this.findPossibleTableRename(oldTable, newSchema)
+          if (possibleRename) {
+            changes.push({
+              type: 'TABLE_RENAMED',
+              table: tableName,
+              oldValue: tableName,
+              newValue: possibleRename.name,
+              isBreaking: false,
+              description: `Table '${tableName}' renamed to '${possibleRename.name}'`,
+              severity: 'low',
+            })
+            continue
+          }
+        }
+
+        changes.push({
+          type: 'TABLE_DROPPED',
+          table: tableName,
+          isBreaking: this.options.tableDropsAreBreaking,
+          breakingReason: this.options.tableDropsAreBreaking
+            ? 'Dropping a table removes all data and breaks existing queries'
+            : undefined,
+          description: `Table '${tableName}' has been dropped`,
+          severity: 'high',
+          metadata: { columnCount: oldTable.columns.length },
+        })
+      }
+    }
+
+    // Check for created tables
+    for (const [tableName, newTable] of newTables) {
+      if (!oldTables.has(tableName)) {
+        changes.push({
+          type: 'TABLE_CREATED',
+          table: tableName,
+          isBreaking: false,
+          description: `Table '${tableName}' has been created`,
+          severity: 'low',
+          metadata: { columnCount: newTable.columns.length },
+        })
+      }
+    }
+
+    return changes
+  }
+
+  /**
+   * Detect column-level changes
+   */
+  private detectColumnChanges(oldSchema: DatabaseSchema, newSchema: DatabaseSchema): SchemaChange[] {
+    const changes: SchemaChange[] = []
+    const oldTables = new Map(oldSchema.tables.map((t) => [t.name, t]))
+    const newTables = new Map(newSchema.tables.map((t) => [t.name, t]))
+
+    // Check changes in tables that exist in both schemas
+    for (const [tableName, oldTable] of oldTables) {
+      const newTable = newTables.get(tableName)
+      if (!newTable) continue
+
+      const oldColumns = new Map(oldTable.columns.map((c) => [c.name, c]))
+      const newColumns = new Map(newTable.columns.map((c) => [c.name, c]))
+
+      // Check for dropped columns
+      for (const [columnName, oldColumn] of oldColumns) {
+        if (!newColumns.has(columnName)) {
+          // Check if this might be a rename
+          if (this.options.detectRenames) {
+            const possibleRename = this.findPossibleColumnRename(oldColumn, newTable)
+            if (possibleRename) {
+              changes.push({
+                type: 'COLUMN_RENAMED',
+                table: tableName,
+                column: columnName,
+                oldValue: columnName,
+                newValue: possibleRename.name,
+                isBreaking: false,
+                description: `Column '${tableName}.${columnName}' renamed to '${possibleRename.name}'`,
+                severity: 'low',
+              })
+              continue
+            }
+          }
+
+          changes.push({
+            type: 'COLUMN_DROPPED',
+            table: tableName,
+            column: columnName,
+            isBreaking: this.options.columnDropsAreBreaking,
+            breakingReason: this.options.columnDropsAreBreaking
+              ? 'Dropping a column breaks existing queries and removes data'
+              : undefined,
+            description: `Column '${tableName}.${columnName}' has been dropped`,
+            severity: 'high',
+            metadata: { dataType: oldColumn.dataType },
+          })
+        }
+      }
+
+      // Check for added columns
+      for (const [columnName, newColumn] of newColumns) {
+        if (!oldColumns.has(columnName)) {
+          // Check if NOT NULL without default
+          const isBreaking =
+            this.options.notNullWithoutDefaultIsBreaking &&
+            !newColumn.isNullable &&
+            !newColumn.hasDefault
+
+          changes.push({
+            type: 'COLUMN_CREATED',
+            table: tableName,
+            column: columnName,
+            isBreaking,
+            breakingReason: isBreaking
+              ? 'Adding NOT NULL column without default requires all existing rows to have a value'
+              : undefined,
+            description: isBreaking
+              ? `Column '${tableName}.${columnName}' added as NOT NULL without default`
+              : `Column '${tableName}.${columnName}' has been added`,
+            severity: isBreaking ? 'high' : 'low',
+            metadata: {
+              dataType: newColumn.dataType,
+              isNullable: newColumn.isNullable,
+              hasDefault: newColumn.hasDefault,
+            },
+          })
+        }
+      }
+
+      // Check for column modifications
+      for (const [columnName, oldColumn] of oldColumns) {
+        const newColumn = newColumns.get(columnName)
+        if (!newColumn) continue
+
+        // Type change
+        if (oldColumn.dataType !== newColumn.dataType) {
+          const isCompatibleChange = this.isCompatibleTypeChange(
+            oldColumn.dataType,
+            newColumn.dataType
+          )
+          const isBreaking = this.options.typeChangesAreBreaking && !isCompatibleChange
+
+          changes.push({
+            type: 'COLUMN_TYPE_CHANGED',
+            table: tableName,
+            column: columnName,
+            oldValue: oldColumn.dataType,
+            newValue: newColumn.dataType,
+            isBreaking,
+            breakingReason: isBreaking
+              ? 'Incompatible type change may cause data loss or conversion errors'
+              : undefined,
+            description: `Column '${tableName}.${columnName}' type changed from ${oldColumn.dataType} to ${newColumn.dataType}`,
+            severity: isBreaking ? 'high' : 'medium',
+            metadata: { compatible: isCompatibleChange },
+          })
+        }
+
+        // Nullability change
+        if (oldColumn.isNullable !== newColumn.isNullable) {
+          const isBreaking = !newColumn.isNullable && !newColumn.hasDefault
+          const description = newColumn.isNullable
+            ? `Column '${tableName}.${columnName}' changed to nullable (safe)`
+            : `Column '${tableName}.${columnName}' changed to NOT NULL`
+
+          changes.push({
+            type: 'COLUMN_NULLABILITY_CHANGED',
+            table: tableName,
+            column: columnName,
+            oldValue: oldColumn.isNullable,
+            newValue: newColumn.isNullable,
+            isBreaking,
+            breakingReason: isBreaking
+              ? 'Making column NOT NULL without default requires all existing rows to be non-null'
+              : undefined,
+            description,
+            severity: isBreaking ? 'high' : 'low',
+          })
+        }
+
+        // Default value changes
+        if (oldColumn.hasDefault !== newColumn.hasDefault) {
+          if (newColumn.hasDefault) {
+            changes.push({
+              type: 'COLUMN_DEFAULT_ADDED',
+              table: tableName,
+              column: columnName,
+              newValue: newColumn.defaultValue,
+              isBreaking: false,
+              description: `Default value added to '${tableName}.${columnName}'`,
+              severity: 'low',
+            })
+          } else {
+            const isBreaking = this.options.removingDefaultsIsBreaking
+
+            changes.push({
+              type: 'COLUMN_DEFAULT_REMOVED',
+              table: tableName,
+              column: columnName,
+              oldValue: oldColumn.defaultValue,
+              isBreaking,
+              breakingReason: isBreaking
+                ? 'Removing default may break applications that rely on it'
+                : undefined,
+              description: `Default value removed from '${tableName}.${columnName}'`,
+              severity: isBreaking ? 'medium' : 'low',
+            })
+          }
+        } else if (
+          oldColumn.hasDefault &&
+          newColumn.hasDefault &&
+          oldColumn.defaultValue !== newColumn.defaultValue
+        ) {
+          changes.push({
+            type: 'COLUMN_DEFAULT_CHANGED',
+            table: tableName,
+            column: columnName,
+            oldValue: oldColumn.defaultValue,
+            newValue: newColumn.defaultValue,
+            isBreaking: false,
+            description: `Default value changed for '${tableName}.${columnName}'`,
+            severity: 'low',
+            metadata: {
+              oldDefault: oldColumn.defaultValue,
+              newDefault: newColumn.defaultValue,
+            },
+          })
+        }
+      }
+    }
+
+    return changes
+  }
+
+  /**
+   * Detect index changes
+   */
+  private detectIndexChanges(oldSchema: DatabaseSchema, newSchema: DatabaseSchema): SchemaChange[] {
+    const changes: SchemaChange[] = []
+    const oldTables = new Map(oldSchema.tables.map((t) => [t.name, t]))
+    const newTables = new Map(newSchema.tables.map((t) => [t.name, t]))
+
+    for (const [tableName, oldTable] of oldTables) {
+      const newTable = newTables.get(tableName)
+      if (!newTable) continue
+
+      const oldIndexes = new Map(oldTable.indexes.map((i) => [i.name, i]))
+      const newIndexes = new Map(newTable.indexes.map((i) => [i.name, i]))
+
+      // Dropped indexes
+      for (const [indexName, oldIndex] of oldIndexes) {
+        if (!newIndexes.has(indexName)) {
+          changes.push({
+            type: 'INDEX_DROPPED',
+            table: tableName,
+            oldValue: indexName,
+            isBreaking: false,
+            description: `Index '${indexName}' on '${tableName}' has been dropped`,
+            severity: 'low',
+            metadata: {
+              columns: oldIndex.columns,
+              isUnique: oldIndex.isUnique,
+            },
+          })
+        }
+      }
+
+      // Created indexes
+      for (const [indexName, newIndex] of newIndexes) {
+        if (!oldIndexes.has(indexName)) {
+          changes.push({
+            type: 'INDEX_CREATED',
+            table: tableName,
+            newValue: indexName,
+            isBreaking: false,
+            description: `Index '${indexName}' created on '${tableName}'`,
+            severity: 'low',
+            metadata: {
+              columns: newIndex.columns,
+              isUnique: newIndex.isUnique,
+            },
+          })
+        }
+      }
+    }
+
+    return changes
+  }
+
+  /**
+   * Detect foreign key changes
+   */
+  private detectForeignKeyChanges(
+    oldSchema: DatabaseSchema,
+    newSchema: DatabaseSchema
+  ): SchemaChange[] {
+    const changes: SchemaChange[] = []
+    const oldTables = new Map(oldSchema.tables.map((t) => [t.name, t]))
+    const newTables = new Map(newSchema.tables.map((t) => [t.name, t]))
+
+    for (const [tableName, oldTable] of oldTables) {
+      const newTable = newTables.get(tableName)
+      if (!newTable) continue
+
+      const oldForeignKeys = oldTable.foreignKeys.map((fk) => this.foreignKeySignature(fk))
+      const newForeignKeys = newTable.foreignKeys.map((fk) => this.foreignKeySignature(fk))
+
+      // Dropped foreign keys
+      for (let i = 0; i < oldTable.foreignKeys.length; i++) {
+        const signature = oldForeignKeys[i]
+        if (signature && !newForeignKeys.includes(signature)) {
+          const fk = oldTable.foreignKeys[i]
+          if (fk) {
+            changes.push({
+              type: 'FOREIGN_KEY_DROPPED',
+              table: tableName,
+              column: fk.column,
+              isBreaking: false,
+              description: `Foreign key on '${tableName}.${fk.column}' referencing '${fk.referencesTable}.${fk.referencesColumn}' has been dropped`,
+              severity: 'medium',
+            })
+          }
+        }
+      }
+
+      // Added foreign keys
+      for (let i = 0; i < newTable.foreignKeys.length; i++) {
+        const signature = newForeignKeys[i]
+        if (signature && !oldForeignKeys.includes(signature)) {
+          const fk = newTable.foreignKeys[i]
+          if (fk) {
+            changes.push({
+              type: 'FOREIGN_KEY_ADDED',
+              table: tableName,
+              column: fk.column,
+              isBreaking: false,
+              description: `Foreign key added on '${tableName}.${fk.column}' referencing '${fk.referencesTable}.${fk.referencesColumn}'`,
+              severity: 'low',
+            })
+          }
+        }
+      }
+    }
+
+    return changes
+  }
+
+  // ============================================================================
+  // Private Methods - Helpers
+  // ============================================================================
+
+  /**
+   * Generate foreign key signature for comparison
+   */
+  private foreignKeySignature(fk: {
+    column: string
+    referencesTable: string
+    referencesColumn: string
+  }): string {
+    return `${fk.column}->${fk.referencesTable}.${fk.referencesColumn}`
+  }
+
+  /**
+   * Check if a type change is compatible (safe to cast)
+   */
+  private isCompatibleTypeChange(oldType: string, newType: string): boolean {
+    const compatibleChanges: Record<string, string[]> = {
+      // Widening numeric types
+      smallint: ['integer', 'bigint', 'numeric', 'decimal'],
+      integer: ['bigint', 'numeric', 'decimal'],
+      bigint: ['numeric', 'decimal'],
+      real: ['double precision', 'numeric', 'decimal'],
+      'double precision': ['numeric', 'decimal'],
+
+      // Character types
+      char: ['varchar', 'text'],
+      varchar: ['text'],
+
+      // Timestamp types
+      'timestamp without time zone': ['timestamp with time zone'],
+      date: ['timestamp without time zone', 'timestamp with time zone'],
+    }
+
+    const normalizedOld = oldType.toLowerCase()
+    const normalizedNew = newType.toLowerCase()
+
+    // Check if varchar/char length is increasing
+    if (normalizedOld.startsWith('varchar') && normalizedNew.startsWith('varchar')) {
+      const oldLength = this.extractLength(normalizedOld)
+      const newLength = this.extractLength(normalizedNew)
+      if (oldLength && newLength && newLength >= oldLength) {
+        return true
+      }
+    }
+
+    return compatibleChanges[normalizedOld]?.includes(normalizedNew) ?? false
+  }
+
+  /**
+   * Extract length from varchar/char type
+   */
+  private extractLength(type: string): number | null {
+    const match = type.match(/\((\d+)\)/)
+    return match?.[1] ? parseInt(match[1], 10) : null
+  }
+
+  /**
+   * Find possible table rename based on column similarity
+   */
+  private findPossibleTableRename(
+    oldTable: TableDefinition,
+    newSchema: DatabaseSchema
+  ): TableDefinition | null {
+    // Look for tables in new schema that have similar column structure
+    for (const newTable of newSchema.tables) {
+      const similarity = this.calculateTableSimilarity(oldTable, newTable)
+      if (similarity > 0.8) {
+        // 80% similar
+        return newTable
+      }
+    }
+    return null
+  }
+
+  /**
+   * Find possible column rename based on type similarity
+   */
+  private findPossibleColumnRename(
+    oldColumn: ColumnDefinition,
+    newTable: TableDefinition
+  ): ColumnDefinition | null {
+    // Look for columns with same type but different name
+    for (const newColumn of newTable.columns) {
+      if (
+        newColumn.dataType === oldColumn.dataType &&
+        newColumn.isNullable === oldColumn.isNullable &&
+        this.calculateStringSimilarity(oldColumn.name, newColumn.name) > 0.6
+      ) {
+        return newColumn
+      }
+    }
+    return null
+  }
+
+  /**
+   * Calculate table similarity based on column structure
+   */
+  private calculateTableSimilarity(table1: TableDefinition, table2: TableDefinition): number {
+    const columns1 = new Set(table1.columns.map((c) => `${c.name}:${c.dataType}`))
+    const columns2 = new Set(table2.columns.map((c) => `${c.name}:${c.dataType}`))
+
+    const intersection = new Set([...columns1].filter((c) => columns2.has(c)))
+    const union = new Set([...columns1, ...columns2])
+
+    return union.size > 0 ? intersection.size / union.size : 0
+  }
+
+  /**
+   * Calculate string similarity (Levenshtein distance based)
+   */
+  private calculateStringSimilarity(str1: string, str2: string): number {
+    const longer = str1.length > str2.length ? str1 : str2
+
+    if (longer.length === 0) return 1.0
+
+    const distance = this.levenshteinDistance(str1, str2)
+    return (longer.length - distance) / longer.length
+  }
+
+  /**
+   * Calculate Levenshtein distance between two strings
+   */
+  private levenshteinDistance(str1: string, str2: string): number {
+    const matrix: number[][] = []
+
+    for (let i = 0; i <= str2.length; i++) {
+      matrix[i] = [i]
+    }
+
+    for (let j = 0; j <= str1.length; j++) {
+      if (matrix[0]) {
+        matrix[0][j] = j
+      }
+    }
+
+    for (let i = 1; i <= str2.length; i++) {
+      for (let j = 1; j <= str1.length; j++) {
+        if (str2[i - 1] === str1[j - 1]) {
+          const prevDiag = matrix[i - 1]?.[j - 1]
+          if (prevDiag !== undefined && matrix[i]) {
+            matrix[i]![j] = prevDiag
+          }
+        } else {
+          const deletion = matrix[i - 1]?.[j] ?? Infinity
+          const insertion = matrix[i]?.[j - 1] ?? Infinity
+          const substitution = matrix[i - 1]?.[j - 1] ?? Infinity
+          if (matrix[i]) {
+            matrix[i]![j] = Math.min(deletion, insertion, substitution) + 1
+          }
+        }
+      }
+    }
+
+    return matrix[str2.length]?.[str1.length] ?? 0
+  }
+
+  /**
+   * Calculate risk level based on breaking changes
+   */
+  private calculateRiskLevel(breakingChanges: SchemaChange[]): 'none' | 'low' | 'medium' | 'high' {
+    if (breakingChanges.length === 0) return 'none'
+
+    const highSeverityCount = breakingChanges.filter((c) => c.severity === 'high').length
+    const mediumSeverityCount = breakingChanges.filter((c) => c.severity === 'medium').length
+
+    if (highSeverityCount > 0) return 'high'
+    if (mediumSeverityCount > 1) return 'medium'
+    if (mediumSeverityCount > 0 || breakingChanges.length > 2) return 'medium'
+    return 'low'
+  }
+
+  /**
+   * Generate summary message
+   */
+  private generateSummary(
+    changes: SchemaChange[],
+    breakingChanges: SchemaChange[],
+    safeChanges: SchemaChange[]
+  ): string {
+    if (changes.length === 0) {
+      return 'No schema changes detected'
+    }
+
+    if (breakingChanges.length === 0) {
+      return `${safeChanges.length} safe change(s) detected - schema is backward compatible`
+    }
+
+    return `${breakingChanges.length} breaking change(s) and ${safeChanges.length} safe change(s) detected - schema is NOT backward compatible`
+  }
+
+  /**
+   * Generate recommendations based on breaking changes
+   */
+  private generateRecommendations(breakingChanges: SchemaChange[]): string[] {
+    const recommendations: string[] = []
+
+    if (breakingChanges.length === 0) {
+      recommendations.push('Schema changes are safe to deploy')
+      return recommendations
+    }
+
+    const hasTableDrop = breakingChanges.some((c) => c.type === 'TABLE_DROPPED')
+    const hasColumnDrop = breakingChanges.some((c) => c.type === 'COLUMN_DROPPED')
+    const hasTypeChange = breakingChanges.some((c) => c.type === 'COLUMN_TYPE_CHANGED')
+    const hasNotNullChange = breakingChanges.some(
+      (c) => c.type === 'COLUMN_CREATED' || c.type === 'COLUMN_NULLABILITY_CHANGED'
+    )
+
+    if (hasTableDrop) {
+      recommendations.push(
+        'Consider renaming tables with _deprecated prefix instead of dropping immediately'
+      )
+      recommendations.push('Ensure all data is backed up before dropping tables')
+    }
+
+    if (hasColumnDrop) {
+      recommendations.push(
+        'Consider renaming columns with _deprecated prefix instead of dropping immediately'
+      )
+      recommendations.push('Deploy code changes that stop using the column before dropping it')
+    }
+
+    if (hasTypeChange) {
+      recommendations.push(
+        'Test type conversions thoroughly to ensure no data loss or corruption'
+      )
+      recommendations.push(
+        'Consider using a temporary column for type changes: add new column, migrate data, drop old column'
+      )
+    }
+
+    if (hasNotNullChange) {
+      recommendations.push('Add columns as nullable first, populate data, then add NOT NULL')
+      recommendations.push('Always provide default values when adding NOT NULL columns')
+    }
+
+    recommendations.push('Consider deploying these changes during a maintenance window')
+    recommendations.push('Ensure database backups are current before running migration')
+
+    return recommendations
+  }
+}
+
+// ============================================================================
+// Exported Functions
+// ============================================================================
+
+/**
+ * Create a new schema compatibility validator
+ */
+export function createCompatibilityValidator(
+  options?: CompatibilityOptions
+): SchemaCompatibilityValidator {
+  return new SchemaCompatibilityValidator(options)
+}
+
+/**
+ * Validate compatibility between two schemas
+ */
+export function validateCompatibility(
+  oldSchema: DatabaseSchema,
+  newSchema: DatabaseSchema,
+  options?: CompatibilityOptions
+): CompatibilityReport {
+  const validator = createCompatibilityValidator(options)
+  return validator.validate(oldSchema, newSchema)
+}
+
+/**
+ * Check if two schemas are backward compatible
+ */
+export function isBackwardCompatible(
+  oldSchema: DatabaseSchema,
+  newSchema: DatabaseSchema,
+  options?: CompatibilityOptions
+): boolean {
+  const validator = createCompatibilityValidator(options)
+  return validator.isBackwardCompatible(oldSchema, newSchema)
+}
+
+/**
+ * Get only safe changes between two schemas
+ */
+export function getSafeChanges(
+  oldSchema: DatabaseSchema,
+  newSchema: DatabaseSchema,
+  options?: CompatibilityOptions
+): SchemaChange[] {
+  const validator = createCompatibilityValidator(options)
+  const report = validator.validate(oldSchema, newSchema)
+  return report.safeChanges
+}
+
+/**
+ * Get only breaking changes between two schemas
+ */
+export function getBreakingChanges(
+  oldSchema: DatabaseSchema,
+  newSchema: DatabaseSchema,
+  options?: CompatibilityOptions
+): SchemaChange[] {
+  const validator = createCompatibilityValidator(options)
+  const report = validator.validate(oldSchema, newSchema)
+  return report.breakingChanges
+}