Doctrine Migrations Multiple Database Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avaibooksports/doctrine-migrations-multiple-database-bundle
   

2. Register the Bundle: Add to config/bundles.php:

   AvaiBookSports\Bundle\MigrationsMutlipleDatabase\DoctrineMigrationsMultipleDatabaseBundle::class => ['all' => true],
   

3. Configure Entity Managers: 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'
   

First Use Case: Running Migrations for a Specific EM

Run migrations for the geonames entity manager:

php bin/console doctrine:migrations:migrate --em=geonames

Implementation Patterns

Workflow: Multi-Database Migration Strategy

1. Organize Migrations by EM:

   • Place migrations for default EM in migrations/Main.
   • Place migrations for geonames EM in migrations/Geonames.
   • Use namespacing to avoid conflicts (e.g., DoctrineMigrations\Main\Version20230101000000).

2. Command Execution:

   • Run for All EMs: Omit --em to execute across all configured EMs.

     php bin/console doctrine:migrations:migrate
     

   • Target Specific EM: Use --em to isolate migrations.

     php bin/console doctrine:migrations:diff --em=geonames
     

3. Generate Migrations: Generate migrations for a specific EM:

   php bin/console doctrine:migrations:generate --em=geonames
   

4. Schema Dumping: Dump schema for a specific EM:

   php bin/console doctrine:migrations:dump-schema --em=geonames
   

Integration Tips

• CI/CD Pipelines: Use --em to parallelize migrations in CI (e.g., run default and geonames in separate jobs).

  # Example GitHub Actions step
  - name: Run Default EM Migrations
    run: php bin/console doctrine:migrations:migrate --em=default
  - name: Run Geonames EM Migrations
    run: php bin/console doctrine:migrations:migrate --em=geonames
  

• Environment-Specific Configs: Override doctrine_migrations_multiple_database.yaml per environment (e.g., config/packages/dev/doctrine_migrations_multiple_database.yaml) to exclude certain EMs in testing.

• Custom Templates: Set custom_template in config to enforce migration file naming conventions:

  doctrine_migrations_multiple_database:
      entity_managers:
          default:
              custom_template: '%kernel.project_dir%/templates/migration.tpl.php'
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Issue: Running doctrine:migrations:diff without --em may fail if migrations share namespaces across EMs.
   • Fix: Always specify --em when using --namespace:

     php bin/console doctrine:migrations:diff --namespace=DoctrineMigrations\Geonames --em=geonames
     

2. Unsupported Configs:

   • Issue: connection and em in doctrine_migrations.yaml are ignored. Use entity_managers in doctrine_migrations_multiple_database.yaml instead.
   • Fix: Migrate all relevant configs to the new bundle’s YAML.

3. Metadata Storage:

   • Issue: Each EM requires its own migration version table (e.g., doctrine_migration_versions_default, doctrine_migration_versions_geonames).
   • Fix: Ensure table_name is unique per EM or use a naming convention like {em}_migration_versions.

4. Command Limitations:

   • Issue: Some commands (e.g., doctrine:migrations:version) may not support --em in older versions.
   • Fix: Check the changelog for supported commands per release.

5. Symfony 6+ Deprecations:

   • Issue: DI deprecations may cause errors in newer Symfony versions (fixed in 0.4.0).
   • Fix: Update to the latest version:

     composer require avaibooksports/doctrine-migrations-multiple-database-bundle:^0.4
     

Debugging Tips

1. Dry Runs: Use --dry-run to preview changes before executing:

   php bin/console doctrine:migrations:migrate --em=geonames --dry-run
   

2. Verbose Output: Add -v or -vv for detailed logs:

   php bin/console doctrine:migrations:status --em=default -vv
   

3. Check EM Configuration: Verify EM names and paths in doctrine_migrations_multiple_database.yaml match your config/packages/doctrine.yaml:

   # Example from doctrine.yaml
   doctrine:
       dbal:
           connections:
               default: { ... }
               geonames: { ... }
       orm:
           entity_managers:
               default: { ... }
               geonames: { ... }
   

Extension Points

1. Custom Migration Factories: Override Doctrine\Migrations\Version\MigrationFactory in config to enforce custom logic:

   doctrine_migrations_multiple_database:
       entity_managers:
           default:
               services:
                   'Doctrine\Migrations\Version\MigrationFactory': 'App\CustomMigrationFactory'
   

2. Post-Migration Hooks: Use Symfony’s event system to trigger actions after migrations:

   // src/EventListener/MigrationListener.php
   namespace App\EventListener;
   
   use Doctrine\Migrations\Event\PostMigrationEventArgs;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class MigrationListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'doctrine.migrations.post_migration' => 'onPostMigration',
           ];
       }
   
       public function onPostMigration(PostMigrationEventArgs $args)
       {
           // Custom logic (e.g., cache invalidation, notifications)
       }
   }
   

3. Dynamic EM Configuration: Load EM configs dynamically (e.g., from a database) by extending the bundle or using a compiler pass:

   // src/DependencyInjection/Compiler/MigrationsCompilerPass.php
   namespace App\DependencyInjection\Compiler;
   
   use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
   use Symfony\Component\DependencyInjection\ContainerBuilder;
   
   class MigrationsCompilerPass implements CompilerPassInterface
   {
       public function process(ContainerBuilder $container)
       {
           if (!$container->has('doctrine_migrations_multiple_database.entity_managers')) {
               return;
           }
           // Dynamically add EMs from a service
       }
   }
   

4. Testing: Mock migrations in PHPUnit by overriding the migration service:

   // tests/Functional/MigrationsTest.php
   use Doctrine\Migrations\Configuration\Connection\ConnectionConfiguration;
   use Doctrine\Migrations\Configuration\Migration\PhpFile;
   
   $container->get('doctrine_migrations_multiple_database.entity_managers')->add(
       'test_em',
       new ConnectionConfiguration([], [], new PhpFile('tests/Migrations'))
   );