Flyway迁移机制概览
flyway是一款强大的数据库迁移工具，它通过维护一个名为flyway_schema_history（或自定义名称）的表来跟踪数据库的版本状态。每次执行迁移时，flyway都会将迁移脚本的元数据（如版本号、描述、类型、执行时间、执行用户等）以及一个关键的校验和（checksum）记录到此表中。校验和是迁移脚本内容的哈希值，用于确保脚本在执行后未被篡改。
当Flyway启动时，它会首先读取项目中的所有迁移脚本，并计算它们的校验和。然后，它会将这些计算出的校验和与flyway_schema_history表中记录的校验和进行比对。如果两者不匹配，Flyway就会认为数据库状态与当前代码库中的迁移脚本不一致，从而触发警告或错误。
“Future”状态的产生与影响
在Flyway中，当一个已成功执行并记录在flyway_schema_history表中的迁移脚本，其内容在后续被修改时，就会导致校验和不匹配。Flyway会识别到数据库中已安装的版本（例如V3）的校验和与当前项目中对应脚本的校验和不一致。
在这种情况下，Flyway可能会将该迁移标记为“Future”状态，或者在flyway:info命令中显示校验和错误。更常见的表现是，它会发出一个警告，指出“Schema "PUBLIC" has a version (X) that is newer than the latest available migration (Y) !”。这里的X是数据库中记录的当前版本（例如V3），而Y则是Flyway在成功校验所有未修改脚本后，所能信任的最新版本（例如V2）。这意味着Flyway认为数据库的实际版本（V3）已经“超前”于它所能有效验证的最新版本（V2），从而阻止任何新的迁移（例如V4）的执行。
示例场景：
假设您按照以下步骤操作：
-
初始迁移成功：
- 添加V1 SQL脚本。
- 添加V2 SQL脚本。
- 添加V3 Java迁移类 (V3__Anonymize.java)。
- 运行mvn flyway:migrate，所有V1、V2、V3均成功执行并记录在flyway_schema_history表中。
- flyway:info输出：
+-----------+--------+---------------------+------+---------------------+---------+ | Category | Version| Description | Type | Installed On | State | +-----------+--------+---------------------+------+---------------------+---------+ | Versioned | 1 | Create person table | SQL | ... | Success | | Versioned | 2 | Add people | SQL | ... | Success | | Versioned | 3 | Anonymize | JDBC | ... | Success | +-----------+--------+---------------------+------+---------------------+---------+
-
修改已迁移脚本：
- 您修改了V3__Anonymize.java类，例如添加了一行System.out.println("something");。
- 再次运行mvn flyway:info，此时V3可能显示为“Future”状态（或校验和不匹配）：
+-----------+--------+---------------------+------+---------------------+---------+ | Category | Version| Description | Type | Installed On | State | +-----------+--------+---------------------+------+---------------------+---------+ | Versioned | 1 | Create person table | SQL | ... | Success | | Versioned | 2 | Add people | SQL | ... | Success | | Versioned | 3 | Anonymize | JDBC | ... | Future | +-----------+--------+---------------------+------+---------------------+---------+
-
尝试新迁移：
- 您添加了一个新的迁移脚本V4__Add_another_person.java。
- 运行mvn flyway:migrate，Flyway会发出警告，并且不会执行V4迁移：
[INFO] Successfully validated 3 migrations (execution time 00:00.020s) [INFO] Current version of schema "PUBLIC": 3 [WARNING] Schema "PUBLIC" has a version (3) that is newer than the latest available migration (2) ! [INFO] Schema "PUBLIC" is up to date. No migration necessary.
此时，flyway:info输出中也不会出现V4。
这个警告明确指出，尽管数据库的当前版本是3，但Flyway能成功验证的最新可用迁移是2。由于V3的校验和不匹配，Flyway无法信任它，因此认为数据库处于一个“未来”状态，无法继续执行新的迁移。
解决方案与最佳实践
解决此问题的核心在于理解Flyway的迁移脚本不可变性原则。
核心原则：已执行的迁移脚本不可变
一旦一个迁移脚本被Flyway执行并成功记录在flyway_schema_history表中，其内容就不应该再被修改。这个原则是Flyway保证数据库版本控制一致性、可重现性和可靠性的基石。如果修改已执行的脚本，就会破坏历史记录的完整性，导致校验和不匹配，进而引发上述“Future”状态和迁移阻塞。
处理已修改脚本的策略
1. 针对开发环境或未推送到主分支的情况：
如果问题发生在开发阶段，且相关修改尚未推送到共享代码库或生产环境，您可以采取以下步骤进行修复：
-
手动修正flyway_schema_history表： 这是最直接的解决方案。您需要连接到数据库，手动删除或修正flyway_schema_history表中对应已修改迁移的记录。
以H2数据库为例，要删除版本为3的记录：
DELETE FROM flyway_schema_history WHERE version = '3';
执行此操作后，Flyway将不再认为V3已成功执行。
-
重新运行迁移： 删除记录后，您可以再次运行mvn flyway:migrate。此时，Flyway会重新检测到V3（即使它已被修改，但现在数据库中没有其成功记录），并尝试执行它。如果V3是您想要的新逻辑，它将以新的校验和重新记录。如果V3的修改是无意的，您应该先恢复V3到原始状态，然后删除记录，再运行migrate。
注意： 如果您希望保留V3的修改，那么在删除历史记录后，Flyway会重新执行V3。如果V3的修改是无意的，请务必先将V3脚本恢复到其原始、正确的版本，再删除历史记录并重新迁移。
2. 正确处理数据库变更：
如果需要对已应用的数据库逻辑进行修改，正确的做法是创建新的迁移脚本，而不是修改旧脚本。
-
新增迁移脚本： 为您的变更创建一个新的迁移脚本，版本号递增（例如V4）。这个新脚本可以包含对旧逻辑的修正、数据更新或任何新的数据库结构变更。
例如，如果您发现V3的匿名化逻辑有缺陷，不应修改V3，而应创建V4：
// V4__Correct_Anonymize_Logic.java public class V4__Correct_Anonymize_Logic extends BaseJavaMigration { public void migrate(Context context) throws Exception { // 在这里实现修正V3逻辑的代码 // 例如，更新之前V3匿名化错误的数据 // 或者添加新的匿名化规则 System.out.println("Applying correction to anonymization logic."); } }这样，Flyway会按照顺序执行V1、V2、V3，然后执行V4，保证了数据库演进历史的完整性和可追溯性。
注意事项
- 生产环境风险： 在生产环境中手动修改flyway_schema_history表是极其危险的操作，可能导致数据不一致或不可恢复的问题。务必在充分测试和备份后谨慎操作，或尽可能避免此类手动干预。
- 版本控制： 确保团队成员都清楚并遵循Flyway迁移脚本不可变性的原则。将迁移脚本视为不可更改的历史记录，任何变更都应通过新增迁移来完成。
- flyway:validate命令： 在执行migrate之前，可以先运行flyway:validate命令。它会检查所有已应用迁移的校验和是否与当前脚本匹配，可以提前发现校验和不匹配的问题，避免在migrate时才遇到阻塞。
总结
Flyway的“Future”状态和迁移阻塞，通常是由于违反了迁移脚本不可变性原则所致。一旦迁移脚本被执行并记录，就应将其视为数据库历史的一部分，不可再修改。任何对数据库结构或数据的变更，都应通过创建新的、版本号递增的迁移脚本来实现。理解并严格遵守这一原则，是有效利用Flyway进行数据库版本控制，确保数据库演进过程稳定可靠的关键。
