数据库规格模板

模板使用路径

1. 在写 SQL 或 ORM migration 前复制迁移模板。
2. 补齐影响行数、锁风险、兼容窗口、回滚触发条件和验证 SQL。
3. 让数据库评审者检查查询计划和迁移顺序。
4. 上线后记录实际耗时、锁等待和验证结果。

安全迁移规格长什么样

模板只有写入真实决策、责任人和证据后才有价值。上方空模板用于搭结构；进入实现前，建议至少写到下面这种具体程度。

Migration: add refund_retry_state
行数：1800 万

计划：
- 先增加 nullable column
- 每批回填 5000 行
- 监控锁等待和写入延迟
- 24 小时无异常读取后再加 NOT NULL

如果复制后的模板仍然缺责任人、证据或回滚字段，就先不要进入实现。

哪些场景必须写 DB Spec

• 核心业务表字段、约束、索引调整。
• 涉及回填、批量重写、长事务的迁移。
• 可能影响高并发查询路径的索引变更。
• 需要兼容旧版本应用或历史任务的变更。

迁移风险控制建议

• 拆分阶段：发布、回填、验证、切流、清理。
• 估算影响行数、执行时长与锁风险。
• 定义回滚触发条件和可执行回滚命令。
• 写清新旧版本读写兼容窗口。

把运维细节写在 Spec 里，通常比线上临场决策更安全。

高风险反模式

• 新增非空字段却没有默认值或回填策略。
• 未验证替代查询计划就直接删除旧索引。
• 高峰时段执行可能阻塞业务的 DDL。
• 未演练回滚就假设“可以随时回退”。

上线前检查清单

• 在接近真实数据量环境验证 migration up/down。
• 约束和索引行为有可复现的压测/查询证据。
• 上线窗口监控、告警、责任人明确。
• 回滚 runbook 已评审并可执行。

配套阅读：边界条件清单、Spec 评审清单。

弱迁移和强迁移对比

弱迁移

“给用户表增加 status 字段，回填数据，然后上线。”这没有说明字段是否可空、默认值、回填批次、旧代码读取行为、锁风险或失败后怎么恢复。

强迁移

“先添加可空 status，默认读取逻辑回退到旧状态字段；每批 10,000 行后台回填，监控锁等待和写入延迟；连续 24 小时无空值读取后再加 NOT NULL。”

强迁移把数据库变更拆成可观察、可暂停、可回滚的阶段。

如何接入发布流程

• 在 PR 中附上 DB Spec，并标明迁移是否需要 DBA、平台或值班负责人评审。
• 对大表变更附上估算行数、批次大小、执行窗口和监控指标。
• 把 migration up/down、兼容窗口和清理步骤拆成独立任务，避免一次发布承担全部风险。
• 上线后记录验证结果，确认约束、索引和业务查询都按规格运行。

评审切片示例：订阅状态字段

数据库变更最适合拆成可观察阶段。下面这个切片把字段添加、读取兼容、回填和约束收紧分开，方便逐步验证。

第一阶段：
- 添加 nullable status
- 写入新订阅时同时写 billing_state 和 status
- 读取时 status 为空则回退到 billing_state

第二阶段：
- 每批回填 5,000 行
- 监控 lock wait、写入延迟和 null read 数量
- 连续 24 小时 null read 为 0 后再加 NOT NULL

回滚：
- 约束前可关闭新 writer 并保留 fallback
- 约束后不删除字段，先恢复读取 fallback

这种写法比“加字段并回填”更长，但它把生产风险拆成了能暂停、能验证、能回滚的步骤。

落地时不要漏的三件事

• 数据量：写清影响行数、回填批次、执行窗口和是否需要低峰运行。
• 兼容窗口：说明旧代码和新代码在同一时间段内如何读写同一份数据。
• 验证方式：上线后用查询、指标或抽样比对证明约束、索引和业务结果符合预期。

数据库规格最重要的不是字段表格，而是把迁移风险变成可观察、可暂停、可恢复的流程。评审结束时，团队应该知道哪一步最危险、如何暂停、谁能批准继续，以及回滚后是否需要保留新字段或补偿数据。

审批前要附上的证据

• 查询证据：附上当前查询计划，以及新增索引或约束后的预期查询计划。
• 规模证据：说明影响行数、批次大小、预计耗时，以及是否在接近生产数据量的环境中验证。
• 兼容证据：展示旧版本应用和新版本应用在迁移窗口内如何共同读写。
• 回滚证据：标明最后一个安全回滚点，以及越过该点后可能需要手动修复的数据。

这些证据能让数据库规格贴近生产行为，而不是只停留在字段设计意图。

没有证据的迁移计划，应该被视为尚未完成评审。

什么时候应该拆分数据库规格

如果一个改动同时包含模型设计、数据回填、应用切流和旧字段清理，不要把所有内容塞进一个长段落。可以把逻辑模型、迁移步骤和验证计划拆成独立部分，让评审者先确认设计，再单独检查发布顺序是否安全。

对于不可逆变更，例如删除字段、收紧约束或清理历史数据，应在执行前写清“安全暂停点”。团队需要知道哪一步还能停下来观察，哪一步必须经过正式发布判断。

常见问题

什么时候必须写回滚方案？

只要变更会修改现有数据、影响旧版本应用、改变约束或索引，就必须写回滚或缓解方案。有些数据变更不能完全回滚，也应写清如何止损。

索引变更要写多细？

至少写预期查询、字段顺序、基数、写入影响和验证方式。对大表索引，还应说明是否需要在线 DDL、分批执行或低峰窗口。

迁移完成后如何关闭风险

数据库规格不应该在变更上线后立刻归档。完成迁移后，还应记录实际执行时间、锁等待、慢查询、回填批次、错误数量和最终验证 SQL。这样下一次类似迁移可以复用真实数据，而不是重新估算风险。

如果上线后发现查询计划、写入延迟或数据一致性与预期不同，应把差异写回规格，并标明后续动作：补索引、调整批次、延长兼容窗口，或暂停删除旧字段。