@dotdo/postgres 0.1.0

package/src/migrations/compatibility.test.ts

@@ -0,0 +1,958 @@
+/**
+ * Tests for Schema Compatibility Validator
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  SchemaCompatibilityValidator,
+  createCompatibilityValidator,
+  validateCompatibility,
+  isBackwardCompatible,
+  getSafeChanges,
+  getBreakingChanges,
+} from './compatibility'
+import type { DatabaseSchema, TableDefinition, ColumnDefinition } from './schema-generator'
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+function createTestSchema(tables: Partial<TableDefinition>[]): DatabaseSchema {
+  return {
+    tables: tables.map((t) => ({
+      name: t.name || 'test_table',
+      schema: t.schema || 'public',
+      columns: t.columns || [],
+      indexes: t.indexes || [],
+      foreignKeys: t.foreignKeys || [],
+      primaryKey: t.primaryKey,
+    })),
+    enums: [],
+    introspectedAt: new Date(),
+  }
+}
+
+function createColumn(overrides: Partial<ColumnDefinition> = {}): ColumnDefinition {
+  return {
+    name: overrides.name || 'test_column',
+    dataType: overrides.dataType || 'text',
+    isNullable: overrides.isNullable ?? true,
+    hasDefault: overrides.hasDefault ?? false,
+    defaultValue: overrides.defaultValue,
+    isPrimaryKey: overrides.isPrimaryKey ?? false,
+    isUnique: overrides.isUnique ?? false,
+    maxLength: overrides.maxLength,
+    references: overrides.references,
+  }
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('SchemaCompatibilityValidator', () => {
+  describe('constructor and basic usage', () => {
+    it('should create a validator with default options', () => {
+      const validator = new SchemaCompatibilityValidator()
+      expect(validator).toBeInstanceOf(SchemaCompatibilityValidator)
+    })
+
+    it('should create a validator with custom options', () => {
+      const validator = new SchemaCompatibilityValidator({
+        columnDropsAreBreaking: false,
+        tableDropsAreBreaking: false,
+      })
+      expect(validator).toBeInstanceOf(SchemaCompatibilityValidator)
+    })
+  })
+
+  describe('table changes', () => {
+    it('should detect table creation as safe change', () => {
+      const oldSchema = createTestSchema([])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer', isPrimaryKey: true })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges).toHaveLength(1)
+      expect(report.safeChanges[0]?.type).toBe('TABLE_CREATED')
+      expect(report.safeChanges[0]?.table).toBe('users')
+    })
+
+    it('should detect table drop as breaking change', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer', isPrimaryKey: true })],
+        },
+      ])
+      const newSchema = createTestSchema([])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(false)
+      expect(report.breakingChanges).toHaveLength(1)
+      expect(report.breakingChanges[0]?.type).toBe('TABLE_DROPPED')
+      expect(report.breakingChanges[0]?.table).toBe('users')
+      expect(report.breakingChanges[0]?.isBreaking).toBe(true)
+    })
+
+    it('should treat table drop as safe when configured', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([])
+
+      const report = validateCompatibility(oldSchema, newSchema, {
+        tableDropsAreBreaking: false,
+      })
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges).toHaveLength(1)
+      expect(report.safeChanges[0]?.isBreaking).toBe(false)
+    })
+  })
+
+  describe('column changes', () => {
+    it('should detect column creation as safe change', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text', isNullable: true }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges).toHaveLength(1)
+      expect(report.safeChanges[0]?.type).toBe('COLUMN_CREATED')
+      expect(report.safeChanges[0]?.column).toBe('email')
+    })
+
+    it('should detect NOT NULL column without default as breaking', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text', isNullable: false, hasDefault: false }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(false)
+      expect(report.breakingChanges).toHaveLength(1)
+      expect(report.breakingChanges[0]?.type).toBe('COLUMN_CREATED')
+      expect(report.breakingChanges[0]?.isBreaking).toBe(true)
+    })
+
+    it('should detect NOT NULL column with default as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({
+              name: 'email',
+              dataType: 'text',
+              isNullable: false,
+              hasDefault: true,
+              defaultValue: "''",
+            }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges).toHaveLength(1)
+      expect(report.safeChanges[0]?.isBreaking).toBe(false)
+    })
+
+    it('should detect column drop as breaking change', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text' }),
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(false)
+      expect(report.breakingChanges).toHaveLength(1)
+      expect(report.breakingChanges[0]?.type).toBe('COLUMN_DROPPED')
+      expect(report.breakingChanges[0]?.column).toBe('email')
+    })
+
+    it('should treat column drop as safe when configured', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text' }),
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema, {
+        columnDropsAreBreaking: false,
+      })
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges).toHaveLength(1)
+    })
+  })
+
+  describe('column type changes', () => {
+    it('should detect incompatible type change as breaking', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'text' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(false)
+      expect(report.breakingChanges).toHaveLength(1)
+      expect(report.breakingChanges[0]?.type).toBe('COLUMN_TYPE_CHANGED')
+      expect(report.breakingChanges[0]?.isBreaking).toBe(true)
+    })
+
+    it('should detect compatible type change as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'bigint' })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'COLUMN_TYPE_CHANGED')).toBe(true)
+    })
+
+    it('should detect varchar length increase as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'name', dataType: 'varchar(50)' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'name', dataType: 'varchar(100)' })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+    })
+
+    it('should detect text to varchar as breaking', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'name', dataType: 'text' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'name', dataType: 'varchar(50)' })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(false)
+    })
+  })
+
+  describe('column nullability changes', () => {
+    it('should detect nullable to NOT NULL as breaking', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'email', dataType: 'text', isNullable: true })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'email', dataType: 'text', isNullable: false, hasDefault: false }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(false)
+      expect(report.breakingChanges).toHaveLength(1)
+      expect(report.breakingChanges[0]?.type).toBe('COLUMN_NULLABILITY_CHANGED')
+    })
+
+    it('should detect NOT NULL to nullable as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'email', dataType: 'text', isNullable: false })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'email', dataType: 'text', isNullable: true })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'COLUMN_NULLABILITY_CHANGED')).toBe(true)
+    })
+
+    it('should detect nullable to NOT NULL with default as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'email', dataType: 'text', isNullable: true })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({
+              name: 'email',
+              dataType: 'text',
+              isNullable: false,
+              hasDefault: true,
+              defaultValue: "''",
+            }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+    })
+  })
+
+  describe('default value changes', () => {
+    it('should detect default value added as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'status', dataType: 'text', hasDefault: false, isNullable: true }),
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({
+              name: 'status',
+              dataType: 'text',
+              hasDefault: true,
+              defaultValue: "'active'",
+              isNullable: true,
+            }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'COLUMN_DEFAULT_ADDED')).toBe(true)
+    })
+
+    it('should detect default value removed as safe by default', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({
+              name: 'status',
+              dataType: 'text',
+              hasDefault: true,
+              defaultValue: "'active'",
+            }),
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'status', dataType: 'text', hasDefault: false })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'COLUMN_DEFAULT_REMOVED')).toBe(true)
+    })
+
+    it('should detect default value removed as breaking when configured', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({
+              name: 'status',
+              dataType: 'text',
+              hasDefault: true,
+              defaultValue: "'active'",
+            }),
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'status', dataType: 'text', hasDefault: false })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema, {
+        removingDefaultsIsBreaking: true,
+      })
+
+      expect(report.isBackwardCompatible).toBe(false)
+      expect(report.breakingChanges.some((c) => c.type === 'COLUMN_DEFAULT_REMOVED')).toBe(true)
+    })
+
+    it('should detect default value changed as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({
+              name: 'status',
+              dataType: 'text',
+              hasDefault: true,
+              defaultValue: "'active'",
+            }),
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({
+              name: 'status',
+              dataType: 'text',
+              hasDefault: true,
+              defaultValue: "'pending'",
+            }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'COLUMN_DEFAULT_CHANGED')).toBe(true)
+    })
+  })
+
+  describe('index changes', () => {
+    it('should detect index creation as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'email', dataType: 'text' })],
+          indexes: [],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'email', dataType: 'text' })],
+          indexes: [
+            {
+              name: 'users_email_idx',
+              columns: ['email'],
+              isUnique: false,
+              isPrimary: false,
+            },
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'INDEX_CREATED')).toBe(true)
+    })
+
+    it('should detect index drop as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'email', dataType: 'text' })],
+          indexes: [
+            {
+              name: 'users_email_idx',
+              columns: ['email'],
+              isUnique: false,
+              isPrimary: false,
+            },
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'email', dataType: 'text' })],
+          indexes: [],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'INDEX_DROPPED')).toBe(true)
+    })
+  })
+
+  describe('foreign key changes', () => {
+    it('should detect foreign key added as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'posts',
+          columns: [createColumn({ name: 'user_id', dataType: 'integer' })],
+          foreignKeys: [],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'posts',
+          columns: [createColumn({ name: 'user_id', dataType: 'integer' })],
+          foreignKeys: [
+            {
+              column: 'user_id',
+              referencesTable: 'users',
+              referencesColumn: 'id',
+            },
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'FOREIGN_KEY_ADDED')).toBe(true)
+    })
+
+    it('should detect foreign key dropped as safe', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'posts',
+          columns: [createColumn({ name: 'user_id', dataType: 'integer' })],
+          foreignKeys: [
+            {
+              column: 'user_id',
+              referencesTable: 'users',
+              referencesColumn: 'id',
+            },
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'posts',
+          columns: [createColumn({ name: 'user_id', dataType: 'integer' })],
+          foreignKeys: [],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'FOREIGN_KEY_DROPPED')).toBe(true)
+    })
+  })
+
+  describe('risk level calculation', () => {
+    it('should return none risk level for no changes', () => {
+      const schema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+
+      const report = validateCompatibility(schema, schema)
+
+      expect(report.riskLevel).toBe('none')
+    })
+
+    it('should return low risk level for safe changes only', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text', isNullable: true }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.riskLevel).toBe('none')
+    })
+
+    it('should return high risk level for table drops', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.riskLevel).toBe('high')
+    })
+  })
+
+  describe('utility functions', () => {
+    it('should check backward compatibility', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text', isNullable: true }),
+          ],
+        },
+      ])
+
+      expect(isBackwardCompatible(oldSchema, newSchema)).toBe(true)
+    })
+
+    it('should get only safe changes', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text', isNullable: true }),
+          ],
+        },
+      ])
+
+      const safeChanges = getSafeChanges(oldSchema, newSchema)
+
+      expect(safeChanges).toHaveLength(1)
+      expect(safeChanges.every((c) => !c.isBreaking)).toBe(true)
+    })
+
+    it('should get only breaking changes', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text' }),
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+
+      const breakingChanges = getBreakingChanges(oldSchema, newSchema)
+
+      expect(breakingChanges).toHaveLength(1)
+      expect(breakingChanges.every((c) => c.isBreaking)).toBe(true)
+    })
+  })
+
+  describe('summary and recommendations', () => {
+    it('should generate summary for no changes', () => {
+      const schema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+
+      const report = validateCompatibility(schema, schema)
+
+      expect(report.summary).toContain('No schema changes detected')
+    })
+
+    it('should generate summary for safe changes', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text', isNullable: true }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.summary).toContain('safe change')
+      expect(report.summary).toContain('backward compatible')
+    })
+
+    it('should generate summary for breaking changes', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text' }),
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.summary).toContain('breaking change')
+      expect(report.summary).toContain('NOT backward compatible')
+    })
+
+    it('should generate recommendations for breaking changes', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text' }),
+          ],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.recommendations.length).toBeGreaterThan(0)
+      expect(report.recommendations.some((r) => r.includes('deprecated'))).toBe(true)
+    })
+
+    it('should generate recommendations for safe deployments', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text', isNullable: true }),
+          ],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.recommendations).toHaveLength(1)
+      expect(report.recommendations[0]).toContain('safe to deploy')
+    })
+  })
+
+  describe('complex scenarios', () => {
+    it('should handle multiple changes across multiple tables', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'email', dataType: 'text' }),
+          ],
+        },
+        {
+          name: 'posts',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'name', dataType: 'text', isNullable: true }),
+          ],
+        },
+        {
+          name: 'posts',
+          columns: [
+            createColumn({ name: 'id', dataType: 'integer' }),
+            createColumn({ name: 'title', dataType: 'text', isNullable: true }),
+          ],
+        },
+        {
+          name: 'comments',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.changes.length).toBeGreaterThan(0)
+      expect(report.breakingChanges.some((c) => c.type === 'COLUMN_DROPPED')).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'COLUMN_CREATED')).toBe(true)
+      expect(report.safeChanges.some((c) => c.type === 'TABLE_CREATED')).toBe(true)
+    })
+
+    it('should handle empty schemas', () => {
+      const emptySchema = createTestSchema([])
+      const report = validateCompatibility(emptySchema, emptySchema)
+
+      expect(report.isBackwardCompatible).toBe(true)
+      expect(report.changes).toHaveLength(0)
+      expect(report.summary).toContain('No schema changes detected')
+    })
+
+    it('should provide detailed metadata for changes', () => {
+      const oldSchema = createTestSchema([
+        {
+          name: 'users',
+          columns: [createColumn({ name: 'id', dataType: 'integer' })],
+        },
+      ])
+      const newSchema = createTestSchema([])
+
+      const report = validateCompatibility(oldSchema, newSchema)
+
+      expect(report.breakingChanges[0]?.metadata).toBeDefined()
+      expect(report.breakingChanges[0]?.metadata?.columnCount).toBe(1)
+    })
+  })
+
+  describe('createCompatibilityValidator', () => {
+    it('should create a validator instance', () => {
+      const validator = createCompatibilityValidator()
+      expect(validator).toBeInstanceOf(SchemaCompatibilityValidator)
+    })
+
+    it('should accept options', () => {
+      const validator = createCompatibilityValidator({
+        columnDropsAreBreaking: false,
+      })
+      expect(validator).toBeInstanceOf(SchemaCompatibilityValidator)
+    })
+  })
+})