Doctrine Migrations Multiple Database Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Multi-DB Schema Evolution: The bundle directly addresses a critical gap in Laravel/Symfony ecosystems where Doctrine Migrations (via DoctrineMigrationsBundle) lacks native support for multi-entity-manager migrations. This aligns with architectures requiring:
  • Microservices-inspired separation (e.g., default for core data, geonames for geospatial extensions).
  • Legacy system integration where existing databases cannot be consolidated.
  • Multi-tenant schemas with isolated migrations per tenant/namespace.
• Laravel Compatibility: While primarily designed for Symfony, the bundle’s YAML configuration and Doctrine ORM integration make it adaptable to Laravel via:
  • Doctrine DBAL (Laravel’s default) or Doctrine ORM (if using laravel-doctrine).
  • Artisan command overrides (e.g., php artisan doctrine:migrations:execute --em=geonames).
• Trade-offs:
  • "Hacky and dirty" implementation: May introduce subtle bugs in edge cases (e.g., transaction boundaries across EMs).
  • No native Laravel support: Requires manual adaptation (e.g., service provider binding, Artisan command aliases).

Integration Feasibility

• Core Dependencies:
  • DoctrineMigrationsBundle (v3.3+): Must be installed (doctrine/doctrine-migrations-bundle).
  • Doctrine DBAL/ORM: Required for entity managers. Laravel’s native Eloquent is incompatible; migration must use Doctrine.
  • Symfony Console: Laravel’s Artisan is a drop-in replacement, but command registration may need adjustments.
• Key Integration Points:
  1. Bundle Registration: Add to Laravel’s config/app.php under providers (Symfony’s bundles.php equivalent).
  2. Configuration: Merge doctrine_migrations_multiple_database.yaml into Laravel’s config (e.g., config/doctrine.php).
  3. Artisan Commands: Override or alias Symfony commands (e.g., php artisan doctrine:migrations:diff --em=geonames).
  4. Service Binding: Register the bundle’s services in Laravel’s container (e.g., via a custom service provider).

Technical Risk

• High:
  • Transaction Isolation: Migrations across EMs may violate ACID properties if not explicitly managed (e.g., using Connection::beginTransaction() per EM).
  • Schema Sync: Risks of orphaned migrations if EM configurations drift (e.g., geonames EM points to a deprecated DB).
  • Laravel-Specific Quirks:
    • Eloquent vs. Doctrine: Mixed usage may cause conflicts (e.g., model inheritance, event listeners).
    • Artisan Command Namespace: Symfony’s doctrine: prefix may clash with Laravel’s commands.
  • Testing Overhead: Multi-EM migrations require complex test fixtures (e.g., Dockerized multi-DB environments).
• Mitigation:
  • Pre-integration spike: Validate with a proof-of-concept using a single non-critical EM.
  • CI/CD Guardrails: Add checks for:
    • EM configuration consistency (e.g., schema_filter in config/doctrine.php).
    • Migration file existence (e.g., Main/ and Geonames/ directories).
  • Rollback Strategy: Document manual rollback procedures for failed multi-EM migrations.

Key Questions

1. Architecture:
   • Are all databases readily accessible from the Laravel app (no network latency or security constraints)?
   • Do migrations require cross-EM dependencies (e.g., foreign keys between default and geonames tables)?
2. Tooling:
   • Will Laravel’s migration system (e.g., php artisan migrate) coexist with Doctrine migrations, or will Doctrine be the sole source of truth?
   • Is Symfony’s Console dependency acceptable, or must commands be rewritten for Artisan?
3. Team Skills:
   • Does the team have Doctrine ORM expertise, or will this introduce a learning curve?
   • Is there DevOps support for multi-DB environments (e.g., backups, monitoring)?
4. Long-Term Viability:
   • Is the bundle actively maintained (despite low stars, check for recent commits/issues)?
   • Are there alternatives (e.g., custom migration scripts, Laravel’s Schema::connection())?

Integration Approach

Stack Fit

• Laravel Compatibility Matrix:

  Component	Compatibility	Workaround
  Doctrine DBAL	✅ Native	Use doctrine/dbal package
  Doctrine ORM	⚠️ Via laravel-doctrine	Requires additional setup
  Eloquent	❌ Incompatible	Migrate to Doctrine ORM
  Symfony Console	⚠️ Partial	Alias commands in app/Console/Kernel.php
  Artisan	✅ With overrides	Bind Symfony commands to Artisan

• Recommended Stack:
  • PHP 8.1+ (for DoctrineMigrationsBundle v3.3+).
  • Laravel 9.x/10.x (for Symfony 6.x compatibility).
  • Doctrine ORM (if using entities) or DBAL (for schema-only migrations).
  • Docker (for local multi-DB testing).

Migration Path

1. Phase 1: Prep Work (1–2 weeks)

   • Audit Dependencies:
     • Install doctrine/doctrine-migrations-bundle and avaibooksports/doctrine-migrations-multiple-database-bundle.
     • Verify doctrine/dbal or doctrine/orm is installed.
   • Configure Doctrine:
     • Add EMs to config/doctrine.php (e.g., default, geonames).
     • Example:

       'entity_managers' => [
           'default' => ['connection' => 'default'],
           'geonames' => ['connection' => 'geonames'],
       ],
       'connections' => [
           'geonames' => ['url' => 'mysql://user:pass@localhost/geonames_db'],
       ],
       

   • Set Up Migrations:
     • Create migrations/Main/ and migrations/Geonames/ directories.
     • Generate initial migrations for each EM:

       php artisan doctrine:migrations:generate --em=default --name="Initial default schema"
       php artisan doctrine:migrations:generate --em=geonames --name="Initial geonames schema"
       

2. Phase 2: Bundle Integration (1 week)

   • Register the Bundle:
     • Add to config/app.php:

       'providers' => [
           // ...
           AvaiBookSports\Bundle\MigrationsMutlipleDatabase\DoctrineMigrationsMultipleDatabaseBundle::class,
       ],
       

   • Configure Multi-EM Migrations:
     • Create config/packages/doctrine_migrations_multiple_database.yaml:

       doctrine_migrations_multiple_database:
           entity_managers:
               default:
                   migrations_paths:
                       DoctrineMigrations\Main: '%kernel.project_dir%/migrations/Main'
               geonames:
                   migrations_paths:
                       DoctrineMigrations\Geonames: '%kernel.project_dir%/migrations/Geonames'
       

   • Alias Symfony Commands:
     • In app/Console/Kernel.php, bind Symfony commands to Artisan:

       protected $commands = [
           // ...
           \Doctrine\Migrations\Tools\Console\Command\MigrateCommand::class,
           \Doctrine\Migrations\Tools\Console\Command\DiffCommand::class,
           // Add custom aliases for multi-EM support
       ];
       

     • Or create Artisan-specific commands extending Symfony’s commands.

3. Phase 3: Validation (1–2 weeks)

   • Test Migrations:
     • Run migrations for each EM:

       php artisan doctrine:migrations:migrate --em=default
       php artisan doctrine:migrations:migrate --em=geonames
       

   • Verify Cross-EM Dependencies:
     • If EMs share data, test with temporary foreign keys disabled during migration.
   • Rollback Testing:
     • Simulate failures and validate rollback:

       php artisan doctrine:migrations:rollback --em=geonames --to=20230101000000
       

4. Phase 4: CI/CD Integration (1 week)

   • Add to Pipeline:
     • Run migrations in CI for each EM (e.g., GitHub Actions):

       - name: Run Doctrine Migrations
         run: |
           php artisan doctrine:migrations:migrate --em