michaelschiemer/docs/database-module-migration-analysis.md

Database Module Migration Analysis

Complete analysis of Database module exception migration requirements.

Module Statistics

• Total PHP Files: 292
• Total Exceptions: 111 exceptions to analyze
  • RuntimeException: 24 instances
  • InvalidArgumentException: 79 instances
  • DatabaseException: 8 instances (already using framework exception)
  • PDOException: 0 (caught and re-thrown)

Exception Categories

Category 1: PDO/Connection Errors (HIGH PRIORITY)

Files: PdoConnection.php, ConnectionPool.php, DatabaseFactory.php Count: 8 existing + need SQLSTATE integration Pattern: Catch PDOException → Re-throw as specific exception

Examples:

// PdoConnection.php:31
throw DatabaseException::simple("Failed to execute query: {$e->getMessage()}", $e);

// ConnectionPool.php:72
throw DatabaseException::create(...)

Migration Strategy:

• Implement SQLSTATE integration FIRST
• Create QueryExecutionException, ConnectionFailedException, etc.
• Extract SQLSTATE from PDOException
• Map to specific DatabaseErrorCode

Category 2: Unsupported Driver/Feature (MEDIUM PRIORITY)

Count: 14 instances Pattern: throw new \RuntimeException("Unsupported database driver: {$driver}")

Files:

• QueryHistoryLogger.php:259
• Schema.php:107, 126, 143, 217
• SchemaBuilderFactory.php:43
• DatabasePlatformInitializer.php:28, 29
• DatabaseOptimizeCommand.php:196
• MigrationDatabaseManager.php:113
• StoredProcedureDefinition.php:213

Migration Target: UnsupportedDriverException or FeatureNotSupportedException

ErrorCode: DatabaseErrorCode::UNSUPPORTED_DRIVER (new)

Examples:

// Before
default => throw new \RuntimeException("Unsupported database driver: {$driver}")

// After
default => throw UnsupportedDriverException::forDriver($driver)

Category 3: Invalid Schema/Compiler Arguments (MEDIUM PRIORITY)

Count: 35 instances (mostly InvalidArgumentException) Pattern: Schema compiler validation, column type validation, index validation

Files:

• PostgreSQLSchemaCompiler.php: 7 instances
• MySQLSchemaCompiler.php: 7 instances
• SQLiteSchemaCompiler.php: 6 instances
• Index/AdvancedIndexDefinition.php: 8 instances
• Index/AdvancedIndexType.php: 4 instances

Decision: KEEP as InvalidArgumentException

• These are configuration/schema definition errors (developer errors)
• Not runtime business logic exceptions
• Similar to constructor validation

Examples to KEEP:

// KEEP - Schema definition validation
throw new \InvalidArgumentException("Unknown column type: {$column->type}")
throw new \InvalidArgumentException("FULLTEXT index not supported by {$driver}")
throw new \InvalidArgumentException('Fill factor must be between 10 and 100')

Category 4: Missing Required Configuration (MEDIUM PRIORITY)

Count: 6 instances Pattern: Missing required data for operation

Files:

• SelectQueryBuilder.php:422, 497, 531
• SchemaBuilder.php:229
• StoredProcedureDefinition.php:164, 188, 217

Migration Target: InvalidQueryStateException or MissingRequirementException

ErrorCode: DatabaseErrorCode::INVALID_STATE or MISSING_REQUIREMENT

Examples:

// SelectQueryBuilder.php:422
throw new \RuntimeException('FROM clause is required');

// After
throw InvalidQueryStateException::missingFromClause();

// SchemaBuilder.php:229
throw new \RuntimeException("Cannot create table '{$this->tableName}' without columns");

// After
throw InvalidSchemaException::tableWithoutColumns($this->tableName);

Category 5: Missing Dependencies/Configuration (LOW PRIORITY)

Count: 5 instances Pattern: Logger not configured, entity manager missing, etc.

Files:

• DatabaseManager.php:111
• ProfilingConnection.php:302
• LazyLoader.php:323, 332

Migration Target: MissingDependencyException

ErrorCode: DatabaseErrorCode::DEPENDENCY_MISSING (new)

Examples:

// DatabaseManager.php:111
throw new \RuntimeException('Clock is required for database profiling');

// After
throw MissingDependencyException::forComponent('Clock', 'Database profiling');

Category 6: Repository/Query Errors (LOW PRIORITY)

Count: 12 instances (InvalidArgumentException) Pattern: Validation in repository methods, pagination, profiling

Files:

• PaginatedResult.php: 4 instances
• Restrictions.php: 2 instances
• QueryProfiler.php: 2 instances
• SlowQueryDetector.php: 1 instance
• Various export/format errors

Decision: MIXED - Analyze case by case

Keep (Constructor Validation):

// PaginatedResult.php:20 - KEEP
throw new \InvalidArgumentException('Current page must be at least 1');

Migrate (Business Logic):

// Restrictions.php:159 - MIGRATE
throw new \InvalidArgumentException('At least one criterion is required');
// Should be: InvalidCriteriaException::empty()

Category 7: Profiling/Monitoring Errors (LOW PRIORITY)

Count: 8 instances Pattern: Configuration errors in profiling/monitoring

Files:

• ProfilingDashboard.php: 4 instances
• QueryProfiler.php, QueryLogger.php, SlowQueryDetector.php

Decision: KEEP most, MIGRATE connection-not-found

Migrate:

// ProfilingDashboard.php:91
throw new \InvalidArgumentException("Connection '$connectionName' not registered");
// Should be: ConnectionNotFoundException::byName($connectionName)

Recommended Exception Classes

1. SQLSTATE-Aware Exceptions (HIGH PRIORITY)

QueryExecutionException       // General query failures with SQLSTATE
ConnectionFailedException     // Connection errors (SQLSTATE 08xxx)
ConstraintViolationException  // Constraint violations (SQLSTATE 23xxx)
DeadlockException            // Deadlocks (SQLSTATE 40001)
TransactionException         // Transaction errors

2. Configuration/Schema Exceptions (MEDIUM PRIORITY)

UnsupportedDriverException    // Unsupported database driver
UnsupportedFeatureException   // Feature not supported by driver
InvalidQueryStateException    // Missing FROM clause, etc.
InvalidSchemaException        // Schema definition errors
MigrationException           // Migration-specific errors

3. Dependency Exceptions (LOW PRIORITY)

MissingDependencyException    // Missing required components
ConnectionNotFoundException   // Connection not found in pool/registry

4. Query Builder Exceptions (LOW PRIORITY)

InvalidCriteriaException      // Criteria/Restrictions errors

Migration Phases

Phase 1: SQLSTATE Foundation (CRITICAL PATH)

Time: 2-3 hours Priority: HIGH

1. Create SqlState value object
2. Create SqlStateErrorMapper service
3. Extend DatabaseErrorCode enum with all codes
4. Write comprehensive tests

Deliverables:

• /src/Framework/Database/ValueObjects/SqlState.php
• /src/Framework/Database/Services/SqlStateErrorMapper.php
• /src/Framework/Exception/Core/DatabaseErrorCode.php (extended)
• /tests/Unit/Framework/Database/SqlStateTest.php

Phase 2: SQLSTATE Exception Classes (CRITICAL PATH)

Time: 3-4 hours Priority: HIGH

1. Create QueryExecutionException with SQLSTATE
2. Create ConnectionFailedException with SQLSTATE
3. Create ConstraintViolationException with SQLSTATE
4. Create DeadlockException with SQLSTATE
5. Create TransactionException

Deliverables:

• 5 exception classes in /src/Framework/Database/Exception/
• Factory methods with rich context
• Integration tests with mock PDOExceptions

Phase 3: Core Connection Migration (CRITICAL PATH)

Time: 2-3 hours Priority: HIGH

1. Update PdoConnection with handlePdoException()
2. Update ConnectionPool exception handling
3. Update DatabaseFactory connection errors
4. Integration tests with real database

Files:

• PdoConnection.php (5 exceptions)
• ConnectionPool.php (3 exceptions)
• DatabaseFactory.php

Phase 4: Configuration Exceptions (MEDIUM PRIORITY)

Time: 2-3 hours Priority: MEDIUM

1. Create UnsupportedDriverException
2. Create UnsupportedFeatureException
3. Create InvalidQueryStateException
4. Create InvalidSchemaException
5. Migrate 14 unsupported driver errors
6. Migrate 6 missing requirement errors

Files:

• Schema.php, SchemaBuilderFactory.php, etc. (14 files)
• SelectQueryBuilder.php, SchemaBuilder.php, etc. (6 files)

Phase 5: Dependency Exceptions (LOW PRIORITY)

Time: 1-2 hours Priority: LOW

1. Create MissingDependencyException
2. Create ConnectionNotFoundException
3. Migrate 5 missing dependency errors
4. Migrate 4 connection-not-found errors

Files:

• DatabaseManager.php, ProfilingConnection.php, LazyLoader.php
• ProfilingDashboard.php

Phase 6: Query Builder Exceptions (LOW PRIORITY)

Time: 1 hour Priority: LOW

1. Create InvalidCriteriaException
2. Migrate Restrictions.php errors (2 instances)

Total Effort Estimate

High Priority (Phases 1-3): 7-10 hours

• SQLSTATE Foundation: 2-3h
• SQLSTATE Exceptions: 3-4h
• Core Connection Migration: 2-3h

Medium Priority (Phase 4): 2-3 hours Low Priority (Phases 5-6): 2-3 hours

Total: 11-16 hours

Success Criteria

Must Have (Phase 1-3)

• SQLSTATE integration complete
• All PDOException catches handled
• Connection errors user-friendly
• Constraint violations descriptive
• Deadlocks with automatic retry
• Integration tests passing

Should Have (Phase 4)

• Unsupported driver errors clear
• Query state errors descriptive
• Schema errors actionable

Nice to Have (Phase 5-6)

• All dependency errors migrated
• Query builder exceptions complete

Risk Assessment

High Risk:

• SQLSTATE mapping completeness - Mitigate: Comprehensive test coverage
• Breaking changes to existing code - Mitigate: Maintain backward compatibility via DatabaseException::simple()
• Performance impact - Mitigate: Benchmark critical paths

Medium Risk:

• Test database setup complexity - Mitigate: Use SQLite for tests
• Migration effort underestimation - Mitigate: Phased approach

Low Risk:

• Documentation completeness - Mitigate: Update docs incrementally

Decision Matrix

What to Migrate

YES - Migrate to specific exceptions:

• ✅ PDOException catches → SQLSTATE-aware exceptions
• ✅ Unsupported driver errors → UnsupportedDriverException
• ✅ Missing FROM clause → InvalidQueryStateException
• ✅ Connection not found → ConnectionNotFoundException
• ✅ Missing dependencies (Clock, etc.) → MissingDependencyException
• ✅ Empty criteria → InvalidCriteriaException

NO - Keep as InvalidArgumentException:

• ❌ Constructor parameter validation
• ❌ Schema compiler column type validation
• ❌ Index type validation
• ❌ Fill factor range validation
• ❌ Page number validation (PaginatedResult constructor)
• ❌ Export format validation (in __construct or similar)

MAYBE - Analyze context:

• ⚠️ Profile ID not found → Consider ProfileNotFoundException
• ⚠️ Slow query threshold validation → Keep as InvalidArgumentException

Files Requiring Changes

Critical Path (Phase 1-3) - 8 files

src/Framework/Database/PdoConnection.php
src/Framework/Database/ConnectionPool.php
src/Framework/Database/DatabaseFactory.php
src/Framework/Database/Middleware/RetryMiddleware.php
src/Framework/Database/ValueObjects/SqlState.php (NEW)
src/Framework/Database/Services/SqlStateErrorMapper.php (NEW)
src/Framework/Database/Exception/QueryExecutionException.php (NEW)
src/Framework/Database/Exception/ConnectionFailedException.php (NEW)
src/Framework/Database/Exception/ConstraintViolationException.php (NEW)
src/Framework/Database/Exception/DeadlockException.php (NEW)
src/Framework/Database/Exception/TransactionException.php (NEW)
src/Framework/Exception/Core/DatabaseErrorCode.php (EXTEND)

Medium Priority (Phase 4) - 20 files

src/Framework/Database/Schema/Schema.php
src/Framework/Database/Platform/SchemaBuilderFactory.php
src/Framework/Database/Platform/DatabasePlatformInitializer.php
src/Framework/Database/QueryBuilder/SelectQueryBuilder.php
src/Framework/Database/Schema/SchemaBuilder.php
src/Framework/Database/StoredProcedure/StoredProcedureDefinition.php
... (14 more schema/driver files)

Low Priority (Phase 5-6) - 10 files

src/Framework/Database/DatabaseManager.php
src/Framework/Database/Profiling/ProfilingConnection.php
src/Framework/Database/LazyLoader.php
src/Framework/Database/Profiling/ProfilingDashboard.php
src/Framework/Database/Criteria/Restrictions.php
... (5 more profiling/query files)

Next Steps

1. Start with Phase 1: SQLSTATE Foundation
2. Validate design with tests before Phase 2
3. Incremental migration: Complete one phase before next
4. Test coverage: ≥80% for new exception classes
5. Documentation: Update database-patterns.md incrementally

Questions to Resolve

1. Should ProfileNotFoundException be created or keep as InvalidArgumentException?
2. Should migration-specific errors get their own exception class or reuse InvalidSchemaException?
3. Should export format errors be migrated or kept as InvalidArgumentException?

Recommendation: Start simple, migrate obvious cases first, defer edge cases to later phases.