# 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 步需在带副本库的机器执行；仓库内以静态检查 + 本清单兜底。