可进入评审的 Markdown
生成结果适合放进工单、PR 或设计评审。它应在实现开始前写清责任人、决策、证据和后续工作。
Migration: add invoice_retry_state 风险： - 表规模：1800 万行 - 锁风险：避免全表重写 发布： - 先增加 nullable column - 分批回填 - 验证后再加约束
数据库规格生成器
定义表、字段、约束和迁移计划——获取即用的数据库规格。复制或下载 Markdown。
db-spec.md
这个工具实际会产出什么
导出之后
把生成的数据库迁移规格当成起点，而不是最终答案。替换示例值，补证据，指定评审人，删掉团队不会维护的字段。
- 把输出放在实现工作旁边。
- 每条验收项都要映射到测试或评审证据。
- 不要粘贴密钥、客户数据或私有事故细节。
什么是数据库规格？
数据库规格是一份结构化的文档，在编写任何 SQL 或 ORM 代码之前，定义表、字段、数据类型、约束、索引和迁移计划。它是应用程序如何存储和检索数据的唯一真相来源。
先写数据库规格再编码可以防止模式漂移，减少迁移问题，并确保每个团队成员都了解数据模型。有了清晰的规格，后端工程师可以实施迁移，应用开发者可以构建查询——双方都清楚存在哪些表和关系。
输出示例
以只增审计日志表为例：字段、约束、索引，以及带回滚方案的两步迁移计划，与生成器实际导出的格式完全一致。
db-spec.md
生成示例
# 审计事件库表设计
## 概述
工作区操作的只增审计日志。API 层写入，合规导出任务读取，应用代码不做更新和删除。
## 表
### audit_events
每条用户可见操作对应一行。
**字段**
| 名称 | 类型 | 可空 | 默认值 | 描述 |
|------|------|----------|---------|-------------|
| `id` | uuid | 否 | gen_random_uuid() | 主键 |
| `workspace_id` | uuid | 否 | — | 所属工作区 |
| `actor_id` | uuid | 是 | — | 系统操作时为空 |
| `action` | text | 否 | — | 如 invoice.reminder_sent |
| `payload` | jsonb | 否 | '{}' | 脱敏后的事件详情 |
| `created_at` | timestamptz | 否 | now() | 写入时间 |
**约束**
| 类型 | 字段 | 详情 |
|------|---------|---------|
| PRIMARY KEY | id | - |
| FOREIGN KEY | workspace_id | → workspaces.id (ON DELETE RESTRICT) |
**索引**
| 名称 | 字段 | 类型 | 唯一 |
|------|---------|------|--------|
| `idx_audit_events_ws_created` | workspace_id, created_at DESC | btree | 否 |
## 迁移计划
| 版本 | 变更 | 回滚 |
|---------|--------|----------|
| 2026_07_01 | 创建 audit_events | 直接删表（尚无读方） |
| 2026_07_08 | 从 app_logs 回填 90 天 | 按来源标记删除回填行 |
## 备注
保留 400 天，由每晚的分区删除任务执行；合规导出按 workspace_id 加 created_at 范围读取，不允许出现缺口。
如何用好这个生成器
先写领域语境，不只写表名
在表和字段之前，先说明这个模式服务哪个业务流程、哪些实体是主记录、哪些表只是审计、缓存或派生视图。语境能防止后续出现看似合理但用途不清的字段。
把约束写成业务规则
唯一索引、外键、非空规则或检查约束，都应该对应产品依赖的行为。如果约束保护金额、权限、合规或数据完整性，要在规格里解释原因。
迁移和回滚一起设计
高风险步骤都应该有缓解方案：扩展-收缩发布、后台回填、dry run 查询、功能开关、兼容窗口，或不会丢失新写入数据的回滚计划。
上线前评审索引影响
索引能提升读取性能，也可能拖慢写入、锁表或增加存储。写清基数、预期查询模式、在线 DDL 要求，以及大表回填是否需要分批。
迁移前的评审问题
数据安全
迁移重复执行是否安全？现有行、空值、重复数据，以及迁移过程中到达的新写入会如何处理？
应用兼容
发布期间，新旧应用版本是否都能工作？要说明默认值、可空阶段、读取兜底和清理时机。
运维证据
哪条 dry run 查询、迁移耗时估算、锁检查或监控信号能证明这个变更足够适合进入生产环境？
弱迁移说明和强迁移说明
弱说明
给 subscriptions 添加 status 字段。回填已有记录。
这没有说明允许值、默认行为、部署顺序、回填需要多久，也没有说明新写入开始后如何回滚。
强说明
先添加可空 status，发布带 billing 状态兜底的读取逻辑，每批 5,000 行回填；当指标显示 24 小时无空值读取后，再强制 NOT NULL。
这描述了安全过渡路径，也给评审者留下可观测的检查点。
导出之后怎么落地
和迁移 PR 放在一起评审
把生成的规格链接到迁移 PR，让评审者能对照检查：规格里的字段意图、约束、索引、回填步骤和实际 SQL 是否一致。数据库变更最怕文档说一套、迁移脚本做另一套。
把高风险步骤变成 runbook
大表回填、在线建索引、不可逆数据清理都应写成操作步骤：负责人、执行窗口、监控查询、暂停条件和回滚判断。只有写成 runbook，线上执行时才不会靠临场记忆。
保留到清理阶段结束
数据库改动通常经历扩展、迁移、验证和收缩四个阶段。临时字段、兼容读取、旧索引和回填任务全部清理前，规格都应继续更新，避免后续团队无法理解当初的迁移边界。
对于影响核心表的大迁移，建议把最终规格附到发布清单里，由发布负责人逐项确认扩展、回填、验证和收缩阶段是否完成，再进入下一步。
如果任何阶段没有明确通过信号，就不要继续执行后续清理步骤。
尤其是删除旧字段或旧索引前，应确认监控中已经没有旧路径读取。
这类验证结果也应写回发布记录。
否则下次迁移会重复同样的不确定性。
完成后的数据库规格应该证明什么
迁移是分阶段的
评审者应该能看到完整顺序：兼容代码发布、schema 扩展、回填、验证查询、收紧约束、删除旧代码和最终清理。看不到验证点的步骤，需要先补监控或查询证据。
回滚有清晰边界
回滚说明要写清哪些内容能撤回，哪些数据可能已经以新结构写入，以及由谁决定暂停、重试还是带着补救措施继续前进。
导出后如何进入评审
补上运维证据
审批前要补影响行数、查询计划、批次大小、锁风险、最后安全回滚点和验证查询。生成器负责结构，证据负责证明这次迁移能在你的生产环境里安全执行。
评审顺序，而不只是字段
请评审者检查部署顺序、回填时机、新旧版本兼容、清理时机和暂停条件。很多数据库事故不是字段定义明显错误，而是发布顺序让系统进入不可恢复状态。
数据库规格常见问题
规格里要包含 SQL 吗？
只有当 SQL 能解释关键决策时才放进去。规格首先应该说明模式意图、约束、迁移顺序、兼容性和回滚；具体 SQL 可以留在迁移文件里。
最常缺失的部分是什么？
回滚。团队经常只列正向迁移，却没说明新版本应用写入旧版本无法理解的数据后如何恢复。把回滚当作设计的一部分，而不是事后补丁。
这个工具如何设计和复查
围绕迁移风险设计
字段重点覆盖容易造成事故的数据库决策：约束、索引、回填顺序、兼容窗口、回滚边界和验证查询。字段设计只是评审的一部分。
按运维产物复查
生成结果会检查发布负责人是否能分阶段执行、观察进度、安全暂停，并解释最后一个安全回滚点。数据库规格应该让生产行为可以被评审。
由编辑维护
作者与编辑：Spec Coding 编辑部。复查流程：编辑政策。纠错与工具问题：联系。最近复查：2026 年 9 月 5 日。