repeatable migration适用于视图、函数、权限等需持续覆盖的场景，不适用于建表、删列等需时序控制的操作；混用时须注意执行顺序与依赖更新，且checksum敏感易致非预期重执行。
repeatable migration 什么时候该用，什么时候不该用
Repeatable migration 的本质是「每次执行都覆盖」，适合那些内容会随业务演进持续变化、但不需要按时间顺序回滚的逻辑。比如视图定义、函数、存储过程、权限配置——它们只关心“当前应该长什么样”，不关心“第几次改的”。
但它不能替代 versioned migration。一旦你写了 V1__init.sql 建了表，后续加字段就不能再扔进 R__add_index_on_user_id.sql 里指望自动生效：Flyway 不保证 repeatable 脚本在 versioned 脚本之后运行，也不校验依赖顺序。
- 适用场景：
R__create_reporting_view.sql、R__set_default_permissions.sql - 不适用场景：建表、删列、修改主键、任何需要精确执行时序的操作
- 典型错误现象：表还没建，repeatable 脚本就去建索引，报
Table 'xxx' doesn't exist - 性能影响：每次
flyway migrate都会重新计算 checksum 并比对内容，大量 R 脚本会拖慢元数据检查速度
versioned migration 的命名和顺序规则必须严格遵守
Flyway 按文件名前缀排序执行，不是按修改时间，也不是按字母顺序。它识别的是 V + 数字 + __ 这个模式，中间的数字部分会被解析为整数比较（所以 V2 在 V10 前面）。
一旦某个 versioned 脚本执行过，它的 checksum 就记在 flyway_schema_history 表里；如果手动改了内容又重跑，会直接失败报 Validate failed: Migration checksum mismatch。
- 正确命名：
V1__create_user_table.sql、V1_1__add_email_to_user.sql（支持小数，但建议用整数+下划线分隔） - 错误命名：
V01__xxx.sql（前导零被忽略，等同于V1）、V1.1__xxx.sql（点号不被识别为版本分隔符） - 不要跳号，也不要重复使用已存在的 version —— 即使本地没执行过，只要 CI 环境跑过，就会冲突
- 跨环境同步时，所有环境必须共享同一套 versioned 脚本历史，否则
flyway repair是临时止痛药，不是解决方案
repeatable 和 versioned 混用时的执行顺序陷阱
Flyway 规定：所有 versioned 脚本按版本号升序执行完，才开始执行 repeatable 脚本。但这里有个关键例外——repeatable 脚本的 checksum 变更后，会在下一次 migrate 时「重新执行」，而 versioned 脚本永远不会重跑（除非用 repair 或删记录）。
这意味着：如果你在 R__build_metrics_view.sql 里引用了 V5__add_metrics_table.sql 新增的表，那没问题；但如果你后来在 V6__rename_metrics_table.sql 里改了表名，而 R__build_metrics_view.sql 还没更新引用，就会在下次 migrate 时报错。
- 常见错误现象：
Error: relation "old_table_name" does not exist，发生在 repeatable 脚本重执行时 - 解决办法：把 repeatable 脚本里对 versioned 对象的依赖，写成条件判断（如 postgresql 的
if EXISTS），或确保每次改 versioned 对象时，同步更新所有相关 R 脚本 - 没有全局依赖图谱，靠人工维护容易漏 —— 尤其当团队多人提交不同类型的迁移时
checksum 计算方式决定哪些改动算“变更”
Flyway 对 versioned 脚本的 checksum 是基于文件完整内容（含注释、空格、换行）计算的；repeatable 脚本也是同样逻辑。这意味着：哪怕只是多了一个空行或改了个注释，checksum 就变，repeatable 脚本就会被标记为“需重执行”。
这个机制本意是保证可重现，但实际中常导致非预期重跑 —— 特别是在 windows / macos 换行符混用、ide 自动格式化、git core.autocrlf 设置不一致时。
- 验证方法：执行
flyway info，看 repeatable 脚本状态是否显示REPEATABLE而不是REPEATABLE (out of date) - 安全做法：所有 SQL 文件统一用 LF 换行，禁用 IDE 的“保存时清理尾部空格”功能（或至少排除 *.sql）
- 不要在 repeatable 脚本里写动态 SQL（比如拼接当前日期），checksum 会永远不匹配，变成无限重执行循环
最麻烦的地方在于：checksum 错误不会立刻报错，它只是让脚本反复执行，可能直到上线后查数据才发现视图逻辑被覆盖错了。这种问题很难复现，也很难从日志里一眼识别。