Mongodb Migrations Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the bundle via Composer:

   composer require antimattr/mongodb-migrations-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Antimattr\MongoDBMigrationsBundle\MongoDBMigrationsBundle::class => ['all' => true],
   ];
   

2. Configuration Update config/packages/antimattr_mongodb_migrations.yaml (or create it) with your MongoDB connection details:

   antimattr_mongodb_migrations:
       db: 'mongodb://localhost:27017'
       db_name: 'your_database'
       collection: 'migrations'
   

3. First Migration Create a migration file in src/Migrations/ (or a custom directory):

   php bin/console make:migration
   

   Example migration (20240101000000_CreateUsersCollection.php):

   <?php
   
   namespace App\Migrations;
   
   use Antimattr\MongoDBMigrationsBundle\Migration\Migration;
   use Doctrine\MongoDB\Collection;
   
   class CreateUsersCollection extends Migration
   {
       public function up(Collection $collection): void
       {
           $collection->createIndex(['email' => 1], ['unique' => true]);
       }
   
       public function down(Collection $collection): void
       {
           $collection->dropIndex('email_1');
       }
   }
   

4. Run Migrations Execute migrations:

   php bin/console mongodb:migrate
   

   Rollback if needed:

   php bin/console mongodb:migrate:rollback
   

5. Verify Check the migrations collection in MongoDB for recorded versions.

First Use Case: Schema Changes

Use this bundle to:

• Add/remove indexes (e.g., up()/down() methods).
• Modify collection schemas (e.g., add/remove fields via updateOne()).
• Seed initial data (e.g., default admin user).

Implementation Patterns

Workflows

1. Version Control

   • Store migrations in version-controlled directories (e.g., src/Migrations/).
   • Name files using YYYYMMDDHHmmss_Description.php for chronological ordering.

2. Atomic Changes

   • Group related schema changes (e.g., indexes + fields) in a single migration.
   • Example: Adding a created_at field and index together.

3. Rollback Safety

   • Always implement down() to reverse changes.
   • Test rollbacks locally before production.

4. Environment-Specific Migrations

   • Use Symfony’s environment variables (%env%) in config to target dev/staging/prod.
   • Example:

     antimattr_mongodb_migrations:
         db: '%env(MONGODB_URL)%'
     

5. Dependency Management

   • Order migrations by filename (lexicographical) or use setOrder() in the bundle config:

     antimattr_mongodb_migrations:
         migrations_order: ['20240101000000_CreateUsers', '20240102000000_AddIndexes']
     

Integration Tips

1. Doctrine ODM Integration If using Doctrine MongoDB ODM, sync migrations with entity changes:

   // In up(): Add index for @Index annotation
   $collection->createIndex(['slug' => 1], ['unique' => true]);
   
   // In down(): Drop the index
   $collection->dropIndex('slug_1');
   

2. Custom Migration Commands Extend the bundle’s command to add pre/post hooks:

   // src/Command/CustomMigrateCommand.php
   use Antimattr\MongoDBMigrationsBundle\Command\MigrateCommand;
   
   class CustomMigrateCommand extends MigrateCommand
   {
       protected function execute(InputInterface $input, OutputInterface $output): int
       {
           $this->logPreMigration($output);
           return parent::execute($input, $output);
       }
   }
   

   Update services.yaml to override the command.

3. Parallel Migrations For large datasets, use batch processing in migrations:

   public function up(Collection $collection): void
   {
       $bulk = [];
       foreach ($this->getBatchData() as $data) {
           $bulk[] = ['insertOne' => ['document' => $data]];
           if (count($bulk) >= 100) {
               $collection->bulkWrite($bulk);
               $bulk = [];
           }
       }
       if (!empty($bulk)) {
           $collection->bulkWrite($bulk);
       }
   }
   

4. Event Listeners Trigger actions before/after migrations via Symfony events:

   # config/services.yaml
   services:
       App\EventListener\MigrationListener:
           tags:
               - { name: kernel.event_listener, event: mongodb.migration.before, method: onMigrationStart }
   

Gotchas and Tips

Pitfalls

1. Collection Existence

   • Issue: Migrations fail if the target collection doesn’t exist.
   • Fix: Use create() in up() if needed:

     public function up(Collection $collection): void
     {
         if (!$collection->exists()) {
             $this->manager->createCollection($collection->getName());
         }
         // Rest of the migration...
     }
     

2. Index Naming Collisions

   • Issue: Duplicate index names cause failures.
   • Fix: Use unique names (e.g., include timestamp):

     $collection->createIndex(['email' => 1], ['unique' => true, 'name' => 'email_1_' . time()]);
     

3. Transaction Limitations

   • Issue: MongoDB multi-document transactions are not supported in all drivers.
   • Fix: Use bulk writes or accept atomicity per operation.

4. Timezone Sensitivity

   • Issue: Filename timestamps may cause ordering issues across timezones.
   • Fix: Use UTC for migration filenames or enforce a consistent timezone in CI/CD.

5. Schema Validation

   • Issue: Schema changes may break existing queries.
   • Fix: Test migrations in a staging environment with real data.

Debugging

1. Dry Runs Enable verbose output to preview changes:

   php bin/console mongodb:migrate --verbose
   

2. Migration Logs Check the migrations collection for executed versions:

   db.migrations.find().sort({ executed_at: -1 }).limit(10);
   

3. Collection Dumps Use mongodump to back up collections before risky migrations:

   mongodump --db your_database --collection users --out /backup/
   

Extension Points

1. Custom Migration Classes Extend Antimattr\MongoDBMigrationsBundle\Migration\Migration to add shared logic:

   abstract class BaseMigration extends Migration
   {
       protected function log(string $message): void
       {
           $this->output->writeln('<comment>[' . get_class($this) . ']</comment> ' . $message);
       }
   }
   

2. Dynamic Config Load migration config from environment variables or files:

   antimattr_mongodb_migrations:
       db: '%env(resolve:MONGODB_URL)%'
       db_name: '%kernel.project_dir%/config/mongodb/name.yaml'
   

3. Migration Tags Tag migrations for conditional execution (e.g., dev-only):

   // In migration class
   public function getTags(): array
   {
       return ['dev'];
   }
   

   Filter in a custom command:

   $migrations = $this->migrationFinder->findMigrations(['tags' => ['dev']]);
   

4. Post-Migration Hooks Use Symfony’s kernel.terminate event to run post-migration tasks:

   // src/EventListener/PostMigrationListener.php
   public function onKernelTerminate(KernelEvents::TERMINATE, Event $event)
   {
       if ($event->getRequest()->attributes->get('migration_running')) {
           $this->notifyTeam('Migrations completed');
       }
   }
   

Configuration Quirks

1. Default Collection The bundle defaults to a migrations collection. Change it via config:

   antimattr_mongodb_migrations:
       collection: 'schema_migrations'
   

2. Connection Switching Use multiple configs for different environments:

   antimattr_mongodb_migrations:
       default_connection: 'default'
       connections:
           default: { db: 'mongodb://localhost:27017', db_name: 'app' }
           staging: { db: 'mongodb://staging:27017', db_name