@dotdo/postgres 0.1.0

package/src/migrations/validator.ts

@@ -0,0 +1,741 @@
+/**
+ * Migration Validator
+ *
+ * Pre-deployment validation for migrations including:
+ * - SQL syntax validation
+ * - Destructive operation detection
+ * - Schema compatibility checks
+ * - Best practice enforcement
+ *
+ * @module migrations/validator
+ */
+
+import type { Migration, QueryExecutor } from './types'
+import type { MigrationRegistry } from './registry'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Validation severity levels
+ */
+export type ValidationSeverity = 'error' | 'warning' | 'info'
+
+/**
+ * Validation issue categories
+ */
+export type ValidationCategory =
+  | 'syntax'
+  | 'destructive'
+  | 'performance'
+  | 'compatibility'
+  | 'best_practice'
+  | 'safety'
+
+/**
+ * Individual validation issue
+ */
+export interface ValidationIssue {
+  /** Severity level */
+  severity: ValidationSeverity
+  /** Issue category */
+  category: ValidationCategory
+  /** Migration ID */
+  migrationId: string
+  /** Human-readable message */
+  message: string
+  /** SQL snippet that caused the issue */
+  sql?: string
+  /** Line number in the SQL (if applicable) */
+  line?: number
+  /** Suggested fix or alternative */
+  suggestion?: string
+  /** Additional context */
+  context?: Record<string, unknown>
+}
+
+/**
+ * Result of validating a single migration
+ */
+export interface MigrationValidationResult {
+  /** Migration ID */
+  migrationId: string
+  /** Whether the migration passed validation */
+  valid: boolean
+  /** Has errors that would prevent migration */
+  hasErrors: boolean
+  /** Has warnings that should be reviewed */
+  hasWarnings: boolean
+  /** All issues found */
+  issues: ValidationIssue[]
+  /** Estimated execution time (if calculable) */
+  estimatedTimeMs?: number
+  /** Tables affected */
+  affectedTables: string[]
+  /** Detected operations */
+  operations: DetectedOperation[]
+}
+
+/**
+ * Result of validating all migrations
+ */
+export interface BatchValidationResult {
+  /** Whether all migrations passed validation */
+  valid: boolean
+  /** Total errors count */
+  errorCount: number
+  /** Total warnings count */
+  warningCount: number
+  /** Per-migration results */
+  results: MigrationValidationResult[]
+  /** Summary of all issues */
+  issues: ValidationIssue[]
+  /** Missing down migrations */
+  missingDownMigrations: string[]
+  /** Version gaps detected */
+  versionGaps: number[]
+  /** Duplicate checksums detected */
+  checksumConflicts: Array<{ migrationIds: string[]; checksum: string }>
+}
+
+/**
+ * Detected SQL operation
+ */
+export interface DetectedOperation {
+  type:
+    | 'CREATE_TABLE'
+    | 'DROP_TABLE'
+    | 'ALTER_TABLE'
+    | 'CREATE_INDEX'
+    | 'DROP_INDEX'
+    | 'CREATE_COLUMN'
+    | 'DROP_COLUMN'
+    | 'ALTER_COLUMN'
+    | 'CREATE_CONSTRAINT'
+    | 'DROP_CONSTRAINT'
+    | 'INSERT'
+    | 'UPDATE'
+    | 'DELETE'
+    | 'TRUNCATE'
+    | 'CREATE_FUNCTION'
+    | 'DROP_FUNCTION'
+    | 'CREATE_TRIGGER'
+    | 'DROP_TRIGGER'
+    | 'CREATE_VIEW'
+    | 'DROP_VIEW'
+    | 'GRANT'
+    | 'REVOKE'
+    | 'OTHER'
+  /** Target object (table name, index name, etc.) */
+  target?: string
+  /** Whether this is a destructive operation */
+  isDestructive: boolean
+  /** Whether this operation requires a lock */
+  requiresLock: boolean
+  /** SQL snippet */
+  sql: string
+}
+
+/**
+ * Validation options
+ */
+export interface ValidationOptions {
+  /**
+   * Check SQL syntax by attempting to parse/explain
+   * Requires a database connection
+   * Default: false
+   */
+  checkSyntax?: boolean
+
+  /**
+   * Warn on destructive operations
+   * Default: true
+   */
+  warnDestructive?: boolean
+
+  /**
+   * Check for missing down migrations
+   * Default: true
+   */
+  checkDownMigrations?: boolean
+
+  /**
+   * Check for version gaps
+   * Default: true
+   */
+  checkVersionGaps?: boolean
+
+  /**
+   * Validate checksum uniqueness
+   * Default: true
+   */
+  checkChecksums?: boolean
+
+  /**
+   * Check for common anti-patterns
+   * Default: true
+   */
+  checkBestPractices?: boolean
+
+  /**
+   * Estimate migration time based on table sizes
+   * Requires a database connection
+   * Default: false
+   */
+  estimateTime?: boolean
+
+  /**
+   * Query executor for syntax checking and time estimation
+   */
+  executor?: QueryExecutor
+}
+
+// ============================================================================
+// SQL Pattern Detection
+// ============================================================================
+
+/**
+ * Patterns for detecting SQL operations
+ */
+const SQL_PATTERNS = {
+  // DDL operations
+  CREATE_TABLE: /CREATE\s+(?:TEMP(?:ORARY)?\s+)?TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/gi,
+  DROP_TABLE: /DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?["']?(\w+)["']?/gi,
+  ALTER_TABLE: /ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?["']?(\w+)["']?/gi,
+  CREATE_INDEX: /CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/gi,
+  DROP_INDEX: /DROP\s+INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+EXISTS\s+)?["']?(\w+)["']?/gi,
+  ADD_COLUMN: /ALTER\s+TABLE\s+["']?(\w+)["']?\s+ADD\s+(?:COLUMN\s+)?["']?(\w+)["']?/gi,
+  DROP_COLUMN: /ALTER\s+TABLE\s+["']?(\w+)["']?\s+DROP\s+(?:COLUMN\s+)?(?:IF\s+EXISTS\s+)?["']?(\w+)["']?/gi,
+  ALTER_COLUMN: /ALTER\s+TABLE\s+["']?(\w+)["']?\s+ALTER\s+(?:COLUMN\s+)?["']?(\w+)["']?/gi,
+  ADD_CONSTRAINT: /ALTER\s+TABLE\s+["']?(\w+)["']?\s+ADD\s+CONSTRAINT/gi,
+  DROP_CONSTRAINT: /ALTER\s+TABLE\s+["']?(\w+)["']?\s+DROP\s+CONSTRAINT/gi,
+
+  // DML operations
+  INSERT: /INSERT\s+INTO\s+["']?(\w+)["']?/gi,
+  UPDATE: /UPDATE\s+["']?(\w+)["']?\s+SET/gi,
+  DELETE: /DELETE\s+FROM\s+["']?(\w+)["']?/gi,
+  TRUNCATE: /TRUNCATE\s+(?:TABLE\s+)?["']?(\w+)["']?/gi,
+
+  // Functions and triggers
+  CREATE_FUNCTION: /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+["']?(\w+)["']?/gi,
+  DROP_FUNCTION: /DROP\s+FUNCTION\s+(?:IF\s+EXISTS\s+)?["']?(\w+)["']?/gi,
+  CREATE_TRIGGER: /CREATE\s+(?:OR\s+REPLACE\s+)?TRIGGER\s+["']?(\w+)["']?/gi,
+  DROP_TRIGGER: /DROP\s+TRIGGER\s+(?:IF\s+EXISTS\s+)?["']?(\w+)["']?/gi,
+
+  // Views
+  CREATE_VIEW: /CREATE\s+(?:OR\s+REPLACE\s+)?(?:MATERIALIZED\s+)?VIEW\s+["']?(\w+)["']?/gi,
+  DROP_VIEW: /DROP\s+(?:MATERIALIZED\s+)?VIEW\s+(?:IF\s+EXISTS\s+)?["']?(\w+)["']?/gi,
+
+  // Privileges
+  GRANT: /GRANT\s+/gi,
+  REVOKE: /REVOKE\s+/gi,
+}
+
+/**
+ * Anti-patterns to detect
+ */
+const ANTI_PATTERNS = [
+  {
+    pattern: /NOT\s+NULL/gi,
+    withoutDefault: /ADD\s+(?:COLUMN\s+)?["']?\w+["']?\s+\w+.*NOT\s+NULL(?!\s+DEFAULT)/gi,
+    message: 'Adding NOT NULL column without DEFAULT requires table rewrite on existing data',
+    suggestion: 'Add column as nullable first, then populate, then add NOT NULL constraint',
+    category: 'performance' as ValidationCategory,
+  },
+  {
+    pattern: /CREATE\s+INDEX\s+(?!CONCURRENTLY)/gi,
+    exclude: /CREATE\s+UNIQUE\s+INDEX/gi, // Unique indexes can't be created concurrently
+    message: 'Creating index without CONCURRENTLY may lock the table',
+    suggestion: 'Use CREATE INDEX CONCURRENTLY if the table has existing data',
+    category: 'performance' as ValidationCategory,
+  },
+  {
+    pattern: /ALTER\s+TABLE.*ALTER\s+COLUMN.*TYPE/gi,
+    message: 'Changing column type may require table rewrite',
+    suggestion: 'Consider adding a new column, migrating data, then dropping the old column',
+    category: 'performance' as ValidationCategory,
+  },
+  {
+    pattern: /DROP\s+COLUMN/gi,
+    message: 'Dropping a column is a destructive operation that cannot be undone',
+    suggestion: 'Consider renaming to _deprecated_columnname and dropping in a later migration',
+    category: 'destructive' as ValidationCategory,
+  },
+  {
+    pattern: /DROP\s+TABLE/gi,
+    message: 'Dropping a table is a destructive operation that may cause data loss',
+    suggestion: 'Consider renaming to _deprecated_tablename and dropping in a later migration',
+    category: 'destructive' as ValidationCategory,
+  },
+  {
+    pattern: /TRUNCATE/gi,
+    message: 'TRUNCATE removes all data from the table',
+    suggestion: 'Ensure this is intentional and consider using DELETE for smaller datasets',
+    category: 'destructive' as ValidationCategory,
+  },
+  {
+    pattern: /UPDATE.*SET.*WHERE/gi,
+    withoutWhere: /UPDATE\s+\w+\s+SET\s+(?!.*WHERE)/gi,
+    message: 'UPDATE without WHERE clause affects all rows',
+    suggestion: 'Add a WHERE clause to limit the scope of the update',
+    category: 'safety' as ValidationCategory,
+  },
+  {
+    pattern: /DELETE.*FROM/gi,
+    withoutWhere: /DELETE\s+FROM\s+\w+(?!\s+WHERE)/gi,
+    message: 'DELETE without WHERE clause removes all rows',
+    suggestion: 'Add a WHERE clause or use TRUNCATE for intentional full deletion',
+    category: 'safety' as ValidationCategory,
+  },
+]
+
+// ============================================================================
+// Migration Validator
+// ============================================================================
+
+/**
+ * Migration Validator
+ *
+ * Validates migrations for safety, performance, and best practices.
+ *
+ * @example
+ * ```typescript
+ * const validator = new MigrationValidator()
+ *
+ * // Validate a single migration
+ * const result = await validator.validateMigration(migration)
+ * if (!result.valid) {
+ *   console.log('Issues:', result.issues)
+ * }
+ *
+ * // Validate all migrations
+ * const batchResult = await validator.validateAll(registry)
+ * ```
+ */
+export class MigrationValidator {
+  private options: {
+    checkSyntax: boolean
+    warnDestructive: boolean
+    checkDownMigrations: boolean
+    checkVersionGaps: boolean
+    checkChecksums: boolean
+    checkBestPractices: boolean
+    estimateTime: boolean
+    executor: QueryExecutor | undefined
+  }
+
+  constructor(options: ValidationOptions = {}) {
+    this.options = {
+      checkSyntax: options.checkSyntax ?? false,
+      warnDestructive: options.warnDestructive ?? true,
+      checkDownMigrations: options.checkDownMigrations ?? true,
+      checkVersionGaps: options.checkVersionGaps ?? true,
+      checkChecksums: options.checkChecksums ?? true,
+      checkBestPractices: options.checkBestPractices ?? true,
+      estimateTime: options.estimateTime ?? false,
+      executor: options.executor,
+    }
+  }
+
+  /**
+   * Detect SQL operations in migration SQL
+   */
+  detectOperations(sql: string): DetectedOperation[] {
+    const operations: DetectedOperation[] = []
+    const normalizedSql = sql.replace(/\s+/g, ' ').trim()
+
+    // Check each pattern
+    for (const [opType, pattern] of Object.entries(SQL_PATTERNS)) {
+      const matches = normalizedSql.matchAll(pattern)
+      for (const match of matches) {
+        const target = match[1] || undefined
+        const isDestructive = opType.startsWith('DROP') || opType === 'TRUNCATE' || opType === 'DELETE'
+        const requiresLock = !opType.includes('CONCURRENTLY') && (
+          opType.startsWith('CREATE') ||
+          opType.startsWith('DROP') ||
+          opType.startsWith('ALTER') ||
+          opType === 'TRUNCATE'
+        )
+
+        const operation: DetectedOperation = {
+          type: opType as DetectedOperation['type'],
+          isDestructive,
+          requiresLock,
+          sql: match[0],
+        }
+        if (target) {
+          operation.target = target
+        }
+        operations.push(operation)
+      }
+    }
+
+    return operations
+  }
+
+  /**
+   * Extract table names from SQL
+   */
+  extractTableNames(sql: string): string[] {
+    const tables = new Set<string>()
+    const operations = this.detectOperations(sql)
+
+    for (const op of operations) {
+      if (op.target) {
+        tables.add(op.target.toLowerCase())
+      }
+    }
+
+    return Array.from(tables)
+  }
+
+  /**
+   * Check for anti-patterns in SQL
+   */
+  checkAntiPatterns(sql: string, migrationId: string): ValidationIssue[] {
+    const issues: ValidationIssue[] = []
+    const normalizedSql = sql.replace(/\s+/g, ' ').trim()
+
+    for (const antiPattern of ANTI_PATTERNS) {
+      const matches = normalizedSql.match(antiPattern.pattern)
+      if (matches) {
+        // Check for more specific pattern if available
+        if (antiPattern.withoutDefault) {
+          const specificMatches = normalizedSql.match(antiPattern.withoutDefault)
+          if (specificMatches) {
+            issues.push({
+              severity: 'warning',
+              category: antiPattern.category,
+              migrationId,
+              message: antiPattern.message,
+              suggestion: antiPattern.suggestion,
+              sql: specificMatches[0],
+            })
+          }
+        } else if (antiPattern.withoutWhere) {
+          const specificMatches = normalizedSql.match(antiPattern.withoutWhere)
+          if (specificMatches) {
+            issues.push({
+              severity: 'warning',
+              category: antiPattern.category,
+              migrationId,
+              message: antiPattern.message,
+              suggestion: antiPattern.suggestion,
+              sql: specificMatches[0],
+            })
+          }
+        } else if (!antiPattern.exclude || !normalizedSql.match(antiPattern.exclude)) {
+          issues.push({
+            severity: 'warning',
+            category: antiPattern.category,
+            migrationId,
+            message: antiPattern.message,
+            suggestion: antiPattern.suggestion,
+            sql: matches[0],
+          })
+        }
+      }
+    }
+
+    return issues
+  }
+
+  /**
+   * Validate SQL syntax using EXPLAIN
+   */
+  async validateSyntax(sql: string, migrationId: string): Promise<ValidationIssue[]> {
+    if (!this.options.executor) {
+      return []
+    }
+
+    const issues: ValidationIssue[] = []
+    const statements = this.splitStatements(sql)
+
+    for (const statement of statements) {
+      const trimmed = statement.trim()
+      if (!trimmed || trimmed.startsWith('--')) {
+        continue
+      }
+
+      try {
+        // For DDL statements, we can't use EXPLAIN, so we wrap in a transaction and rollback
+        // This is a best-effort check
+        await this.options.executor.query('BEGIN')
+        try {
+          await this.options.executor.query(trimmed)
+          await this.options.executor.query('ROLLBACK')
+        } catch (error) {
+          await this.options.executor.query('ROLLBACK')
+          throw error
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error)
+        issues.push({
+          severity: 'error',
+          category: 'syntax',
+          migrationId,
+          message: `SQL syntax error: ${errorMessage}`,
+          sql: trimmed.substring(0, 100) + (trimmed.length > 100 ? '...' : ''),
+        })
+      }
+    }
+
+    return issues
+  }
+
+  /**
+   * Split SQL into individual statements
+   */
+  private splitStatements(sql: string): string[] {
+    // Simple split on semicolons, handling quoted strings
+    const statements: string[] = []
+    let current = ''
+    let inString = false
+    let stringChar = ''
+
+    for (let i = 0; i < sql.length; i++) {
+      const char = sql[i]
+      const prevChar = sql[i - 1]
+
+      if (!inString && (char === "'" || char === '"')) {
+        inString = true
+        stringChar = char
+      } else if (inString && char === stringChar && prevChar !== '\\') {
+        inString = false
+      }
+
+      if (char === ';' && !inString) {
+        if (current.trim()) {
+          statements.push(current.trim())
+        }
+        current = ''
+      } else {
+        current += char
+      }
+    }
+
+    if (current.trim()) {
+      statements.push(current.trim())
+    }
+
+    return statements
+  }
+
+  /**
+   * Validate a single migration
+   */
+  async validateMigration(migration: Migration): Promise<MigrationValidationResult> {
+    const issues: ValidationIssue[] = []
+    const operations = this.detectOperations(migration.up)
+    const affectedTables = this.extractTableNames(migration.up)
+
+    // Check for basic required fields
+    if (!migration.id || !migration.id.trim()) {
+      issues.push({
+        severity: 'error',
+        category: 'syntax',
+        migrationId: migration.id || 'unknown',
+        message: 'Migration ID is required',
+      })
+    }
+
+    if (!migration.up || !migration.up.trim()) {
+      issues.push({
+        severity: 'error',
+        category: 'syntax',
+        migrationId: migration.id,
+        message: 'Migration up SQL is required',
+      })
+    }
+
+    if (migration.version < 1) {
+      issues.push({
+        severity: 'error',
+        category: 'syntax',
+        migrationId: migration.id,
+        message: 'Migration version must be a positive integer',
+      })
+    }
+
+    // Check for missing down migration
+    if (this.options.checkDownMigrations && !migration.down) {
+      issues.push({
+        severity: 'warning',
+        category: 'best_practice',
+        migrationId: migration.id,
+        message: 'Migration has no down SQL - rollback not supported',
+        suggestion: 'Add down SQL to enable rollback capability',
+      })
+    }
+
+    // Check for anti-patterns
+    if (this.options.checkBestPractices) {
+      issues.push(...this.checkAntiPatterns(migration.up, migration.id))
+    }
+
+    // Warn on destructive operations
+    if (this.options.warnDestructive) {
+      for (const op of operations) {
+        if (op.isDestructive) {
+          issues.push({
+            severity: 'warning',
+            category: 'destructive',
+            migrationId: migration.id,
+            message: `Destructive operation detected: ${op.type}${op.target ? ` on ${op.target}` : ''}`,
+            sql: op.sql,
+            suggestion: 'Ensure this is intentional and data backup is available',
+          })
+        }
+      }
+    }
+
+    // Check SQL syntax if enabled
+    if (this.options.checkSyntax && this.options.executor) {
+      issues.push(...await this.validateSyntax(migration.up, migration.id))
+    }
+
+    // Check down migration syntax if available
+    if (this.options.checkSyntax && this.options.executor && migration.down) {
+      const downIssues = await this.validateSyntax(migration.down, migration.id)
+      for (const issue of downIssues) {
+        issue.message = `Down migration: ${issue.message}`
+        issues.push(issue)
+      }
+    }
+
+    const hasErrors = issues.some((i) => i.severity === 'error')
+    const hasWarnings = issues.some((i) => i.severity === 'warning')
+
+    return {
+      migrationId: migration.id,
+      valid: !hasErrors,
+      hasErrors,
+      hasWarnings,
+      issues,
+      affectedTables,
+      operations,
+    }
+  }
+
+  /**
+   * Validate all migrations in a registry
+   */
+  async validateAll(registry: MigrationRegistry): Promise<BatchValidationResult> {
+    const migrations = registry.getMigrations()
+    const results: MigrationValidationResult[] = []
+    const allIssues: ValidationIssue[] = []
+    const missingDownMigrations: string[] = []
+    const versionGaps: number[] = []
+    const checksumConflicts: Array<{ migrationIds: string[]; checksum: string }> = []
+
+    // Validate each migration
+    for (const migration of migrations) {
+      const result = await this.validateMigration(migration)
+      results.push(result)
+      allIssues.push(...result.issues)
+
+      if (!migration.down) {
+        missingDownMigrations.push(migration.id)
+      }
+    }
+
+    // Check for version gaps
+    if (this.options.checkVersionGaps && migrations.length > 0) {
+      const versions = migrations.map((m) => m.version).sort((a, b) => a - b)
+      const minVersion = versions[0] ?? 1
+      const maxVersion = versions[versions.length - 1] ?? 1
+
+      for (let v = minVersion; v <= maxVersion; v++) {
+        if (!versions.includes(v)) {
+          versionGaps.push(v)
+          allIssues.push({
+            severity: 'warning',
+            category: 'compatibility',
+            migrationId: `version_${v}`,
+            message: `Missing migration for version ${v}`,
+          })
+        }
+      }
+    }
+
+    // Check for duplicate checksums
+    if (this.options.checkChecksums) {
+      const checksumMap = new Map<string, string[]>()
+
+      for (const migration of migrations) {
+        const checksum = await this.calculateChecksum(migration.up)
+        const existing = checksumMap.get(checksum) || []
+        existing.push(migration.id)
+        checksumMap.set(checksum, existing)
+      }
+
+      for (const [checksum, migrationIds] of checksumMap) {
+        if (migrationIds.length > 1) {
+          checksumConflicts.push({ migrationIds, checksum })
+          allIssues.push({
+            severity: 'warning',
+            category: 'compatibility',
+            migrationId: migrationIds.join(', '),
+            message: `Duplicate migration content detected: ${migrationIds.join(', ')}`,
+            suggestion: 'Migrations should have unique content',
+          })
+        }
+      }
+    }
+
+    const errorCount = allIssues.filter((i) => i.severity === 'error').length
+    const warningCount = allIssues.filter((i) => i.severity === 'warning').length
+
+    return {
+      valid: errorCount === 0,
+      errorCount,
+      warningCount,
+      results,
+      issues: allIssues,
+      missingDownMigrations,
+      versionGaps,
+      checksumConflicts,
+    }
+  }
+
+  /**
+   * Calculate checksum for migration content
+   */
+  private async calculateChecksum(content: string): Promise<string> {
+    const encoder = new TextEncoder()
+    const data = encoder.encode(content)
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+    const hashArray = Array.from(new Uint8Array(hashBuffer))
+    return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('')
+  }
+}
+
+/**
+ * Create a migration validator
+ */
+export function createMigrationValidator(options?: ValidationOptions): MigrationValidator {
+  return new MigrationValidator(options)
+}
+
+/**
+ * Validate a single migration
+ */
+export async function validateMigration(
+  migration: Migration,
+  options?: ValidationOptions
+): Promise<MigrationValidationResult> {
+  const validator = createMigrationValidator(options)
+  return validator.validateMigration(migration)
+}
+
+/**
+ * Validate all migrations in a registry
+ */
+export async function validateMigrations(
+  registry: MigrationRegistry,
+  options?: ValidationOptions
+): Promise<BatchValidationResult> {
+  const validator = createMigrationValidator(options)
+  return validator.validateAll(registry)
+}