# 已在客户库上跑过的迁移，为什么绝不能再改

> Flyway、Rails 和 Liquibase 都会记录每次执行的迁移，正确做法永远是新增文件，而不是改旧文件。

原文: https://fdetimes.net/zh/tools/never-edit-applied-flyway-migration/

在一个已经执行过的迁移文件里，只把一个 `int` 改成 `bigint`，Flyway 就可能让整条流水线停下来。这不是工具故意挑剔，而是在提醒你：客户的数据库和你仓库里的文件，现在讲的是两个不同的故事。

你给客户带去一个新功能，这个功能需要多一列或多一张表。同样的变更要在你的机器上、测试环境里，以及客户的数据库上执行，而客户数据库你可能只有几个小时的访问权限。

Flyway 是 Redgate 的产品，官方将其定位为数据库变更管理方案。其核心以 Apache 2.0 许可证开源，由 Redgate 与众多贡献者共同维护。弄懂 Flyway 为什么禁止修改旧文件，也就弄懂了它如何防止各个环境渐行渐远。

## 每个文件是一个版本，版本不能重复

版本化迁移遵循一套命名约定，Flyway 文档用 `V001.002__NewTwitterColumn.sql` 作为示例：字母 V、版本号、两个下划线，然后是描述。每个版本化迁移的版本号必须唯一。

执行 migrate 时，Flyway 先按版本顺序执行待处理的版本化迁移，再执行内容有变化的可重复迁移。一家物流公司订单系统的迁移目录可能是这样的：

```
sql/
  V001__create_orders.sql
  V002__add_weight_column.sql
  V003__add_delivery_window.sql
```

如果客户数据库已经执行到 V002，你带去 V003，那么待处理的只有 V003。文档示例里的版本号带前导零。最好从第一天起就沿用这种编号，这样任何人打开目录，看到的文件顺序也是对的。

## 校验和记住了执行过什么

Flyway 每执行一个迁移，都会保存它的校验和；SQL 文件用的是 CRC32。目标数据库里的 schema 历史表记录了已执行的迁移，以及每个文件的校验和。如果某个迁移的名称、类型或校验和与执行时不同，validate 命令就会失败。

回到开头的场景。V002 创建了一个 `int` 类型的 `weight` 列，已经在客户的 staging 环境执行过。一位工程师觉得这一列应该是 `bigint`，于是直接打开 V002，改完就提交了。

staging 上仍是 `int` 列，而任何从仓库全新构建的数据库都会是 `bigint`。两个数据库已经分叉，却没人察觉，直到 validate 运行，报告这个版本化迁移的校验和与 schema 历史中的记录不符。这个错误在分叉蔓延到生产环境之前拦住了你。

## 正确做法：先恢复原样，再继续往前

Flyway 文档把“不修改已执行的迁移”视为最佳实践，并建议用新迁移向前推进。在上面的例子里，你把 V002 恢复成一字不差的原始内容，再新增一个文件 `V004__widen_weight_to_bigint.sql`，其中用一条 ALTER 语句修改列类型。

此后每个环境都走同样的步骤。staging 只执行 V004。新数据库先执行原始的 V002，一直执行到 V004，最终结果完全一致，历史记录也如实反映了发生过的一切。

**要点:** 执行过的迁移就是历史。要改动，就写一个新迁移。

## 不只是 Flyway

这条原则并非某个工具的怪癖。Rails 通过 `schema_migrations` 表追踪已执行的迁移，因此已执行的文件事后被修改，也不会再次执行。所以 Rails 指南建议写一个新迁移，而不是修改已经提交的迁移。

Liquibase 每次执行或检查 changeset 时都会重新计算校验和，并与存储的值比对。Liquibase 给出的修复方式几乎就是上面例子的翻版：恢复原始 changeset，再新增一个 changeset，把列从 int 改为 bigint。

所以无论技术栈是什么，接手任何客户项目的第一周都要问两个问题：迁移工具把历史存在哪张表里？它会不会比对校验和？

## 校验和发现不了什么？

校验和只保护文件。如果客户那边有人打开 SQL 客户端手工加了一个索引，没有任何文件发生变化，validate 也就无从报告。

这时漂移报告就派上用场了。Flyway Check 的 SQL Server 教程使用 `-drift` 选项生成报告，列出不是由任何已执行迁移创建的 schema 对象。

设想在项目启动时，对客户的 staging 环境跑一次这份报告：如果那个手工添加的索引出现在报告里，就去问数据库负责人是否保留它，然后把它写进一个新迁移，让仓库和数据库重新一致。

还有一个局限：顺序正确，并不能让一条糟糕的 SQL 语句变得安全。一个在高峰时段锁住大表的迁移，无论版本管理得多规范，照样会锁表。编写能在客户真实数据上安全运行的迁移，仍然是你的工作。

## 先学什么，简历上写什么

学习顺序是：命名约定、migrate 如何挑选待处理文件，然后是如何读懂 schema 历史表。validate 和漂移报告放到最后，因为只有理解了工具记录的是什么，才能正确解读它的报错。

简历上不要只写“熟悉 Flyway”。

如果职位描述提到客户数据库，面试时就准备好一个这样的故事。

你不会是最后一个接触客户数据库的人。一条没人偷偷改过的迁移链，是你能留给下一位接手者最可靠的东西。

**本周动手试试:**

- 在测试数据库上创建 V001、V002、V003 三个文件，执行 migrate，然后打开 schema 历史表逐行阅读
- 在 V002 执行后修改其中一行，再运行 validate，看看校验和不匹配的报错长什么样
- 把 V002 恢复原样，把想要的改动写进 V004，然后再次运行 validate 和 migrate

## 信源

- [Flyway - Redgate](https://www.red-gate.com/products/flyway/)

- [flyway/flyway: Flyway by Redgate • Database Migrations Made Easy](https://github.com/flyway/flyway)

- [Versioned migrations - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/fd/versioned-migrations-273973333.html)

- [Migrations - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/fd/migrations-271585107.html)

- [Validate - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/flyway/reference/commands/validate)

- [Flyway schema history table - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/fd/flyway-schema-history-table-273973417.html)

- [Tutorial - Using Flyway Check with SQL Server - Redgate Flyway - Product Documentation](https://documentation.red-gate.com/fd/tutorial-using-flyway-check-with-sql-server-277579354.html)

- [Active Record Migrations — Ruby on Rails Guides](https://guides.rubyonrails.org/active_record_migrations.html)

- [What affects changeset checksums](https://www.liquibase.com/blog/what-affects-changeset-checksums)
