@dotdo/postgres 0.1.0

package/dist/migrations/compatibility.js

@@ -0,0 +1,651 @@
+/**
+ * Schema Compatibility Validator
+ *
+ * Validates schema changes for compatibility before running migrations.
+ * Detects breaking changes, safe changes, and generates compatibility reports.
+ *
+ * @module migrations/compatibility
+ */
+// ============================================================================
+// 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 {
+    options;
+    constructor(options = {}) {
+        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, newSchema) {
+        const changes = [];
+        // 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, newSchema) {
+        const report = this.validate(oldSchema, newSchema);
+        return report.isBackwardCompatible;
+    }
+    /**
+     * Get only safe changes from a compatibility report
+     */
+    getSafeChanges(changes) {
+        return changes.filter((c) => !c.isBreaking);
+    }
+    /**
+     * Get only breaking changes from a compatibility report
+     */
+    getBreakingChanges(changes) {
+        return changes.filter((c) => c.isBreaking);
+    }
+    // ============================================================================
+    // Private Methods - Change Detection
+    // ============================================================================
+    /**
+     * Detect table-level changes
+     */
+    detectTableChanges(oldSchema, newSchema) {
+        const changes = [];
+        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
+     */
+    detectColumnChanges(oldSchema, newSchema) {
+        const changes = [];
+        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
+     */
+    detectIndexChanges(oldSchema, newSchema) {
+        const changes = [];
+        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
+     */
+    detectForeignKeyChanges(oldSchema, newSchema) {
+        const changes = [];
+        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
+     */
+    foreignKeySignature(fk) {
+        return `${fk.column}->${fk.referencesTable}.${fk.referencesColumn}`;
+    }
+    /**
+     * Check if a type change is compatible (safe to cast)
+     */
+    isCompatibleTypeChange(oldType, newType) {
+        const compatibleChanges = {
+            // 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
+     */
+    extractLength(type) {
+        const match = type.match(/\((\d+)\)/);
+        return match?.[1] ? parseInt(match[1], 10) : null;
+    }
+    /**
+     * Find possible table rename based on column similarity
+     */
+    findPossibleTableRename(oldTable, newSchema) {
+        // 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
+     */
+    findPossibleColumnRename(oldColumn, newTable) {
+        // 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
+     */
+    calculateTableSimilarity(table1, table2) {
+        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)
+     */
+    calculateStringSimilarity(str1, str2) {
+        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
+     */
+    levenshteinDistance(str1, str2) {
+        const matrix = [];
+        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
+     */
+    calculateRiskLevel(breakingChanges) {
+        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
+     */
+    generateSummary(changes, breakingChanges, safeChanges) {
+        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
+     */
+    generateRecommendations(breakingChanges) {
+        const recommendations = [];
+        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) {
+    return new SchemaCompatibilityValidator(options);
+}
+/**
+ * Validate compatibility between two schemas
+ */
+export function validateCompatibility(oldSchema, newSchema, options) {
+    const validator = createCompatibilityValidator(options);
+    return validator.validate(oldSchema, newSchema);
+}
+/**
+ * Check if two schemas are backward compatible
+ */
+export function isBackwardCompatible(oldSchema, newSchema, options) {
+    const validator = createCompatibilityValidator(options);
+    return validator.isBackwardCompatible(oldSchema, newSchema);
+}
+/**
+ * Get only safe changes between two schemas
+ */
+export function getSafeChanges(oldSchema, newSchema, options) {
+    const validator = createCompatibilityValidator(options);
+    const report = validator.validate(oldSchema, newSchema);
+    return report.safeChanges;
+}
+/**
+ * Get only breaking changes between two schemas
+ */
+export function getBreakingChanges(oldSchema, newSchema, options) {
+    const validator = createCompatibilityValidator(options);
+    const report = validator.validate(oldSchema, newSchema);
+    return report.breakingChanges;
+}
+//# sourceMappingURL=compatibility.js.map