DoctrineMigrationsBundle 数据库迁移工具完全指南

DoctrineMigrationsBundle 数据库迁移工具完全指南

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

什么是数据库迁移

数据库迁移是一种安全更新数据库结构的标准化方法，它解决了开发和生产环境数据库同步的难题。相比直接执行SQL语句或使用doctrine:schema:update命令，迁移提供了更可靠的方式来管理数据库结构变更。

核心优势

1. 版本控制：每次数据库变更都有明确记录
2. 可回滚：支持撤销已执行的变更
3. 环境一致性：确保所有环境的数据库结构一致
4. 团队协作：便于多人协作开发时的数据库同步

安装配置

安装步骤

使用Composer安装最新稳定版：

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

基本配置

配置文件通常位于config/packages/doctrine_migrations.yaml，主要配置项包括：

doctrine_migrations:
    migrations_paths:
        'App\Migrations': '%kernel.project_dir%/src/Migrations'
    connection: default
    storage:
        table_storage:
            table_name: 'migration_versions'
            version_column_name: 'version'
    transactional: true

核心命令详解

常用命令速查

| 命令 | 功能描述 | |------|----------| | doctrine:migrations:status | 查看迁移状态 | | doctrine:migrations:generate | 生成空白迁移文件 | | doctrine:migrations:diff | 对比实体与数据库生成迁移 | | doctrine:migrations:migrate | 执行待处理的迁移 | | doctrine:migrations:execute | 执行特定迁移版本 |

典型工作流

1. 生成迁移：

   php bin/console doctrine:migrations:diff
   

2. 检查生成内容： 打开生成的迁移文件，确认SQL语句符合预期

3. 执行迁移：

   php bin/console doctrine:migrations:migrate
   

高级特性

自定义迁移模板

可通过配置使用自定义模板：

doctrine_migrations:
    custom_template: 'templates/migration.tpl'

事务处理配置

doctrine_migrations:
    all_or_nothing: true  # 全部成功或全部回滚
    transactional: true   # 每个迁移单独事务

依赖注入支持

通过自定义工厂实现服务注入：

// src/Migrations/Factory/MigrationFactory.php
class MigrationFactory implements MigrationFactoryInterface 
{
    public function createVersion(string $migrationClassName): AbstractMigration
    {
        $migration = new $migrationClassName();
        if ($migration instanceof ContainerAwareInterface) {
            $migration->setContainer($this->container);
        }
        return $migration;
    }
}

最佳实践

1. 开发阶段：

   • 每次实体变更后立即生成迁移
   • 在测试环境验证迁移脚本

2. 部署阶段：

   • 先备份生产数据库
   • 使用--dry-run参数预检查
   • 分批次执行大型迁移

3. 团队协作：

   • 将迁移文件纳入版本控制
   • 避免直接修改已提交的迁移文件

常见问题解决

忽略特定表

配置Doctrine忽略非托管表：

doctrine:
    dbal:
        schema_filter: ~^(?!ignore_)~

元数据存储不同步

出现metadata storage is not up to date错误时：

1. 检查数据库连接字符串中的服务器版本
2. MariaDB需使用mariadb-前缀
3. 执行同步命令：

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

迁移文件示例

典型迁移类结构：

final class Version20230101000000 extends AbstractMigration
{
    public function up(Schema $schema): void
    {
        $this->addSql('CREATE TABLE user (...)');
    }

    public function down(Schema $schema): void
    {
        $this->addSql('DROP TABLE user');
    }
}

通过掌握DoctrineMigrationsBundle，开发者可以系统化地管理数据库变更，确保应用在不同环境间迁移时的数据一致性。

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