DoctrineMigrationsBundle 升级指南：从 2.x 到 3.0 的关键变更解析

DoctrineMigrationsBundle 升级指南：从 2.x 到 3.0 的关键变更解析

DoctrineMigrationsBundle Symfony integration for the doctrine/migrations library 项目地址: https://gitcode.com/gh_mirrors/do/DoctrineMigrationsBundle

前言

DoctrineMigrationsBundle 作为 Symfony 生态中管理数据库迁移的核心组件，在 3.0 版本中进行了多项重要改进。本文将详细解析从 2.x 升级到 3.0 版本时需要关注的关键变更点，帮助开发者顺利完成迁移工作。

配置结构变更

迁移路径与命名空间配置

在 3.0 版本中，迁移路径和命名空间的配置方式发生了显著变化：

旧版配置方式（2.x）

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

新版配置方式（3.0）

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

这个变更使得配置更加清晰，同时支持定义多个迁移路径和对应的命名空间，为大型项目提供了更好的灵活性。

元数据存储配置

元数据表的配置结构也进行了重构：

旧版配置（2.x）

doctrine_migrations:
    table_name: 'migration_versions'
    column_name: 'version'
    column_length: 14
    executed_at_column_name: 'executed_at'

新版配置（3.0）

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

主要变更点：

1. 配置项被组织到 storage.table_storage 命名空间下
2. column_name 重命名为 version_column_name
3. column_length 默认值从 14 变为 191，以更好地支持长版本号

默认表名变更

特别需要注意的是，默认表名从 migration_versions 变更为 doctrine_migration_versions。如果项目之前没有显式配置表名，升级后必须明确指定：

doctrine_migrations:
    storage:
        table_storage:
            table_name: 'migration_versions'

配置完成后，需要执行以下命令同步元数据存储：

php bin/console doctrine:migrations:sync-metadata-storage

废弃的功能

迁移名称配置

3.0 版本移除了 name 配置项：

旧版配置（2.x）

doctrine_migrations:
    name: 'Application Migrations'

新版（3.0） 该配置项已完全移除，无需替代方案。

底层库变更

升级到 3.0 版本会自动将 doctrine/migrations 库升级到 3.0 版本，带来以下重要变化：

1. 容器注入变更：不再自动为实现了 ContainerAwareInterface 的迁移类注入容器。如需依赖注入，应使用自定义迁移工厂。

2. 其他不兼容变更：底层库的更多变更细节建议参考官方升级文档。

升级建议

1. 备份现有迁移：在升级前备份所有迁移文件和数据库状态
2. 逐步测试：先在开发环境测试升级过程
3. 检查自定义迁移：如果迁移类依赖容器注入，需要重构为使用自定义工厂
4. 更新CI/CD流程：确保构建流程适应新的配置方式

结语

DoctrineMigrationsBundle 3.0 通过重构配置结构，提供了更清晰的语义和更好的扩展性。虽然升级过程需要一些配置调整，但这些改进为项目的长期维护带来了显著优势。按照本文指南逐步操作，开发者可以顺利完成升级过渡。

DoctrineMigrationsBundle Symfony integration for the doctrine/migrations library 项目地址: https://gitcode.com/gh_mirrors/do/DoctrineMigrationsBundle