# Flyway 迁移规范模板（task-192）

> 新增数据库迁移一律在本仓库 `src/main/resources/db/` 追加 `V{N+1}__*.sql`（版本号在现有最大版本之上加 1），
> 每个迁移文件头必须引用本模板并补齐六项必填。**只追加，绝不修改已部署的历史迁移**（会破坏 Flyway 校验和）。

复制以下头注释到新迁移文件顶部并逐项填写：

```sql
-- =============================================================
-- 迁移 V{N+1}__<短横线描述>
-- 模板：docs/flyway-migration-template.md（task-192）
--
-- 1. 变更目的：<一句话说明要解决什么问题 / 为何变更>
-- 2. 影响表与数据量：<表名：预计行数 / 全表或增量；例如 biz_file_result ~50w 全表>
-- 3. 锁表风险：<是否 ONLINE / 是否加锁 / 大表索引类需 ALGORITHM=INPLACE 评估；风险高则拆批或窗口执行>
-- 4. 验证 SQL：<迁移后用于核对的行数 / 抽样语句，见下方示例>
-- 5. 回滚步骤：<V{N}__<desc>.sql 或补丁脚本路径；无回滚写明原因>
-- 6. 上线窗口：<建议窗口，例如 业务低峰 02:00-06:00；双节点滚动>
-- =============================================================

-- 迁移语句（DDL/DML）…

-- 可选验证（与头注释第 4 项对应）
-- SELECT COUNT(*) FROM <table>;
```

## 六项必填说明

| # | 字段 | 要求 | 反例 |
|---|------|------|------|
| 1 | 变更目的 | 一句话，写清"为什么" | 留空 / 只写表名 |
| 2 | 影响表与数据量 | 每张被改表名 + 预计行数量级 | "涉及多表" 不含表名 |
| 3 | 锁表风险 | 指出 DDL 是否 INPLACE/排他、大表评估 | "无风险" 不说明依据 |
| 4 | 验证 SQL | 迁移后可跑的核对语句 | 缺失 |
| 5 | 回滚步骤 | 回滚脚本路径或明确不可回滚原因 | 缺失 |
| 6 | 上线窗口 | 建议时段 + 是否滚动 | 缺失 |

## 示例验证 SQL（供第 4 项复制）

```sql
-- 迁移后行数与迁移前基线对比
SELECT COUNT(*) FROM biz_file_result;
-- 新索引是否生效（用于索引类迁移）
SHOW INDEX FROM biz_file_result WHERE Key_name = 'idx_task_module';
-- 抽样数据
SELECT id, task_id, status, updated_at FROM biz_file_task ORDER BY id DESC LIMIT 5;
```

## 使用约束

- 版本号在 `src/main/resources/db/` 最大现有版本上加 1（当前 ≥ V109），不抢号、不重复。
- 不修改、不删除任何已执行过的历史迁移文件。
- 上线走双节点滚动 + 生产库先 `flyway validate`，失败即停。