Symfony数据库迁移实战：版本控制教程

Doctrine Migrations 是 Symfony 生产环境中不可或缺的数据库版本控制核心基础设施，它通过自动生成带时间戳的 PHP 迁移文件（如 Version20260310190500.php）将实体变更转化为可追溯、可重复、事务安全的结构演进流程；正确实践要求先修改实体再执行 `doctrine:migrations:diff` 自动生成迁移，严格验证状态与 SQL 兼容性后执行 `migrate`，并手动编写与 `up()` 严格对称的 `down()` 方法以保障可靠回滚——所有操作都依托 `doctrine_migration_versions` 表进行状态管理，严禁手动删表或绕过迁移机制，否则将彻底破坏数据库演进的确定性与可维护性。

Doctrine Migrations 是 Symfony 项目里控制数据库结构版本的默认方式，不是“可选插件”，而是生产环境必须依赖的基础设施。它不靠手动 SQL 或临时脚本，而是把每次表结构变更固化为带时间戳的 PHP 类，靠 doctrine:migrations:migrate 命令驱动执行与回滚。

怎么生成迁移文件：别直接写，先改实体再 diff

新手常误以为要手写 up() 和 down() —— 实际上绝大多数场景应让 Doctrine 自动推导差异。流程是：改 Entity 类（比如加个 $email 属性并配好 @ORM\Column），然后运行：

php bin/console doctrine:migrations:diff

这条命令会对比当前实体映射和数据库实际结构，自动生成一个类似 Version20260310190500.php 的迁移文件到 migrations/ 目录。它生成的 SQL 是安全、幂等的（比如对已存在的字段不会重复 ADD COLUMN）。

• 如果没生成任何内容，检查是否漏了 @ORM\Entity 或 @ORM\Table 注解
• 若提示 “No changes detected”，可能是数据库里已有该字段但实体没同步，或用了 doctrine:generate:entities 这类过时命令（Symfony 5.4+ 已弃用）
• doctrine:migrations:diff 默认只作用于默认连接；多数据库时需加 --em=other_manager

执行迁移前必须确认的三件事

执行 doctrine:migrations:migrate 不是“点一下就完事”，它会真实修改数据库。跳过验证容易炸库。

• 先跑 doctrine:migrations:status：看 “Available migrations” 是否有未执行项，“Executed migrations” 是否包含你刚生成的版本号
• 检查生成的迁移文件里有没有 $this->addSql() 手写语句——如果有，确认它是否兼容目标数据库（如 MySQL 8 vs PostgreSQL 的 UUID 写法）
• 生产环境务必开启事务保护：确保 config/packages/doctrine_migrations.yaml 中 transactional: true（默认已是 true，但老项目可能被改过）

特别注意：up() 方法里调用 $schema->createTable() 是安全的，但直接写 $this->addSql('DROP TABLE users') 在 up() 里属于高危操作，除非你明确知道后果。

回滚失败常见原因：down() 方法不是自动反向生成的

很多人以为 doctrine:migrations:rollback 能无脑倒退，结果报错说 down() 里缺字段或表已删。这是因为 Doctrine 不会自动推导 down() 逻辑 —— 它只保证你写的 down() 能把 up() 的效果撤销。

• 如果你在 up() 里用 $table->addColumn('status', 'string')，那 down() 就得写 $table->dropColumn('status')，不能留空
• 删除整张表？down() 必须显式调用 $schema->dropTable('xxx')，否则 rollback 时表还挂着，下次 migrate 又报 “table already exists”
• 使用 $this->addSql() 写的原生 SQL，down() 里也得手写对应逆操作（比如 CREATE → DROP，ALTER → 没有通用逆操作，得按需还原）

真正可靠的回滚，前提是 down() 方法经过本地测试，且和 up() 形成严格对称。

迁移状态存在哪？别手动删表

Doctrine 记录哪些迁移已执行，靠的是数据库里的 doctrine_migration_versions 表（Sylius 等项目可能叫 sylius_migrations）。有人遇到“迁移重复执行”就去删表，这是最危险的操作之一。

• 删表会导致所有迁移记录丢失，下次 migrate 会重跑全部历史迁移，极大概率报错（比如重复建表）
• 正确做法是用 doctrine:migrations:execute --down [version] 单独回退某次，或用 --no-interaction --force 强制标记某次为已执行（仅调试用）
• 表名由配置决定：storage.table_storage.table_name，默认是 doctrine_migration_versions，改名后记得同步检查

迁移的本质是状态机，不是脚本集合。一旦绕过它的状态跟踪机制，后续所有操作都会失去确定性。

文中关于Symfony的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Symfony数据库迁移实战：版本控制教程》文章吧，也可关注golang学习网公众号了解相关技术文章。