DoctrineMigrationsBundle

In version 3.0.0, the configuration for the metadata table definition was moved under a storage.table_storage hierarchy.

Note on table_name: The default value for table_name changed from migration_versions to doctrine_migration_versions. If you did not explicitly specify a table_name in your previous version, you must declare it explicitly in 3.0.0 to avoid losing access to your migration data.

# Before 3.0.0
doctrine_migrations:
    table_name: 'migration_versions'
    column_name: 'version'
    column_length: 14
    executed_at_column_name: 'executed_at'

# After 3.0.0
doctrine_migrations:
    storage:
        table_storage:
            table_name: 'migration_versions'
            version_column_name: 'version'
            version_column_length: 191
            executed_at_column_name: 'executed_at'

By default, the doctrine:migrations:diff command will attempt to remove any database tables that are not defined in your Doctrine entities. To prevent this for custom tables (e.g., tables managed by other tools), configure a schema_filter in your Doctrine DBAL settings. This filter uses a regular expression to ignore specific tables or sequences at the DBAL level.

# config/packages/doctrine.yaml
# Example: Ignore all tables prefixed by `t_`
doctrine:
    dbal:
        schema_filter: ~^(?!t_)~

In version 3.0.0, the configuration structure for migration namespaces and directories changed. Replace the dir_name and namespace keys with the migrations_paths key.

# Before 3.0.0
doctrine_migrations:
    dir_name: '%kernel.project_dir%/src/Migrations'
    namespace: DoctrineMigrations

# After 3.0.0
doctrine_migrations:
    migrations_paths:
        'DoctrineMigrations': '%kernel.project_dir%/src/Migrations'

To install the bundle in a Symfony application, use Composer. If you are not using Symfony Flex, you must manually register the bundle in your config/bundles.php file.

$ composer require doctrine/doctrine-migrations-bundle "^3.0"

// config/bundles.php

return [
    // ...
    Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle::class => ['all' => true],
];

When upgrading to version 4.0.0, ensure your environment and dependencies meet the new requirements.

Dependency Requirements:

• PHP 8.4 or higher is required (support for < 8.4 is dropped).
• doctrine/orm 3 or higher is required.
• doctrine/doctrine-bundle 3 or higher is required.

Breaking Changes:

• Final/Internal Classes: Several classes are now marked as final and @internal. They should not be extended or referenced outside of the bundle.
• Type Declarations: Type declarations have been added to all method signatures and properties. You may need to update your custom code to match these new types.
• Container-Aware Migrations: Support for container-aware migrations has been removed. Migrations implementing ContainerAwareInterface will no longer have the container injected automatically. The ContainerAwareMigrationFactory class has also been removed.

You can skip a specific migration by manually adding it to the migration_versions table. This tells Doctrine that the migration has already been executed, so it will be ignored in future runs. Note: You must use single quotes around the class name for the command to work correctly.

$ php bin/console doctrine:migrations:version 'App\Migrations\Version123' --add

If you have updated your metadata table configuration (e.g., moving to the new storage.table_storage structure in version 3.0.0), you must run the following command to synchronize the changes:

doctrine:migrations:sync-metadata-storage

Instead of writing migrations manually, you can compare your Doctrine mapping (entities) with your current database structure to generate migration classes automatically.

1. Update your entities (e.g., add a new User entity).
2. Run the diff command to generate a new migration file containing the necessary SQL.
3. Run the migrate command to apply the changes to your database.

If you have already created your schema using doctrine:schema:create and want to start using migrations without running all previous migration files, you can tell Doctrine to skip all existing versions.