crawler-plugin/backend-java/docs/flyway-migration-drill.md

Flyway 迁移演练 runbook（task-201）

目的：在副本库上验证新增迁移可干净执行、验证 SQL 通过、可回滚、可幂等重跑，且全程不动历史迁移。 本文档为演练步骤与检查清单；on-DB 执行需运维在有副本库的机器按步骤进行（本地/CI 无库时不执行 migrate）。

前置

• 副本库：与生产同版本（MySQL 8.4），已执行到当前最大版本 V108（与生产一致）。
• 拿到待演练的新迁移：src/main/resources/db/V{N+1}__*.sql，头注释引用 docs/flyway-migration-template.md（task-192）六项必填齐全。

演练步骤

1. 基线核对：flyway -url=<副本> info 确认版本、描述、checksum 与生产一致；git log 确认历史 V1..V108 未被改动。
2. validate：flyway validate —— 校验历史迁移 checksum，任何历史文件被改动会立刻失败（违规红线）。
3. 干净迁移：把待演练迁移放入后 flyway migrate；记录成功版本、耗时。
4. 验证 SQL：执行迁移头注释第 4 项的验证 SQL（行数/索引/SHOW INDEX），确认结果符合预期。
5. 回滚验证：按头注释第 5 项回滚脚本回滚新迁移（若无回滚脚本，验证迁移可幂等重跑替代）。
6. 幂等重跑：回滚后再 flyway migrate 一次，确认可重复、无残留副作用。
7. 锁窗口评估：索引类迁移记录执行耗时与是否 ONLINE，结合表数据量估算生产锁窗口。
8. 收尾：记录结论到本清单；生产窗口按 template 第 6 项执行。

离线静态检查（本仓库 JUnit 已覆盖）

• 迁移文件整数版本 1..N 连续、无重复（MigrationInventoryTest，task-193）。
• 迁移校验和可复算稳定（同一文件两次读 SHA-256 一致，MigrationInventoryTest）。
• 新迁移命名合规、模板六字段可引用（FlywayMigrationTemplateDocTest，task-192）。

完成检查

• 副本库 flyway migrate 干净执行（版本升至目标）
• 验证 SQL 通过
• 回滚验证通过 / 幂等重跑通过
• 锁窗口已按表量估算并记录
• 历史迁移未被改动（flyway validate 通过）

注：CI/本地无数据库环境时，本 runbook 的第 3-7 步需在带副本库的机器执行；仓库内以静态检查 + 本清单兜底。