القائمة
数据库工程——schema 设计、迁移安全、查询优化、数据完整性。用于新增/修改表结构、编写迁移、设计索引、优化慢查询、处理数据约束或数据修复计划
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
结构化脑暴——发散探索 + 收敛评估。当想法模糊、面临开放性问题或需要方案对比，或提到"脑暴""想法""方案对比""怎么办"
恢复保存的工作上下文。当新 session 需要继续之前的工作，或提到"恢复""restore""继续上次"
保存工作上下文。当需要保存当前工作状态供后续 session 恢复，或提到"保存""save""checkpoint""挂起"
架构决策记录（ADR）。当面临技术选型、架构决策、方案取舍需要记录，或提到"ADR""决策记录""为什么这样做"
发布或导出检查 → Go/No-Go → 归档。当审查通过后需要上线或交付最终产物，或提到"发布""上线""ship""Go/No-Go"
合并 PR → 等待 CI → 验证生产。当 PR 已创建需要合并到主分支并验证部署，或提到"合并""merge""PR""land"
| name | build-backend-database |
| description | 数据库工程——schema 设计、迁移安全、查询优化、数据完整性。用于新增/修改表结构、编写迁移、设计索引、优化慢查询、处理数据约束或数据修复计划 |
build-workflow-execute 继续下一个切片build-workflow-execute 继续下一个切片references/database-examples.md（详细示例、说辞完整表、零停机案例、事务隔离级别、数据修复模板）数据库约束是数据的类型系统。应用验证是补充，数据库约束是最后防线。
执行规则：
所有 schema 变化必须进入迁移文件，不允许生产手改无记录。
执行规则：
生产迁移默认使用 expand → migrate/backfill → contract。不一次性完成破坏性 schema 变更。
执行规则：
大表 ALTER、回填、建索引必须评估锁表风险、耗时和分批策略。
执行规则：
CONCURRENTLY）写完复杂查询立即 EXPLAIN / EXPLAIN ANALYZE 验证执行计划。
执行规则：
ANALYZE 更新统计信息按 WHERE、JOIN、ORDER BY 模式建索引，不按字段盲目建。
执行规则：
findMany() / list() 后循环内再查库 = N+1。
执行规则：
多表一致性写入必须定义事务边界。
执行规则：
生产数据修复不是 seed，也不是普通 migration。三者不混用：Migration 改 schema（有序、需 rollback plan）；Seed 填开发数据（幂等、可重复）；Data Repair 修生产数据。
执行规则：
项目约定（团队统一即可，非绝对标准）：表名复数 snake_case、列名 snake_case、主键 UUID 或 BIGSERIAL、时间 TIMESTAMPTZ（不裸用 TIMESTAMP）、布尔前缀 is_/has_、软删除优先 deleted_at。短例详见 references/database-examples.md §1-2。
| 级别 | 场景 | 要求 |
|---|---|---|
| Low | 可空列、普通索引、小表约束 | UP + DOWN，staging 验证 |
| Medium | 回填、新增 NOT NULL、改默认值 | + 分步迁移 + backfill 策略 |
| High | DROP/重命名列、改字段类型、大表索引/回填 | + expand-contract + 备份 + 回滚验证 |
| Critical | CASCADE 删除、无 WHERE DML、不可逆变更 | + 人工审批 + 备份恢复演练 |
Checkpoint：每个约束都有业务语义，Schema 约定一致。
Checkpoint：迁移有 rollback plan，风险已分级。
Checkpoint：staging 验证 + rollback plan 已测试。
按查询模式建索引 → EXPLAIN ANALYZE → 确认无 N+1。 Checkpoint：每个索引有查询说明，关键查询延迟达标。
| 说辞 | 现实 | 后果 |
|---|---|---|
| "约束在应用代码做就行" | 直接 SQL 更新、数据修复、ETL 都绕过应用层。数据库约束是最后防线。 | 数据损坏风险 ×10；垃圾数据无校验入库 |
| "先加列，索引以后再建" | 查询慢就是现在。建索引成本低。 | 大表无索引查询慢 ×100-1000；补索引需锁表或停服 |
| "迁移不用 DOWN——不会回滚" | 出问题时凌晨 3 点写回滚脚本更痛苦。 | 有 DOWN = 5 秒回滚；无 DOWN = 30-60 分钟高风险手写 |
| "大表回填一次性跑完" | 大表全表 UPDATE 会锁行、膨胀、长事务。 | 长事务 → 连接池耗尽 → 服务不可用 |
完整 8 条说辞表详见 references/database-examples.md §7。
.findMany() / list() 后循环内还有数据库查询（N+1）CASCADE 删表SELECT * 在生产代码中| 验证项 | 失败表现 | 处理方式 |
|---|---|---|
| 迁移无 rollback plan | 只有 UP，没有回滚 | 补写 DOWN 或备份+补偿方案；不可逆操作需 deprecated + 分步 |
| 关键列无约束 | NOT NULL / CHECK 缺失 | 在 DDL 层添加约束 |
| 大表 Seq Scan + 高选择性 | EXPLAIN 显示全表扫描 | 为查询模式添加组合索引 |
| N+1 查询 | findMany 循环中嵌套查询 | 改为 include/JOIN 批量查询 |
| 时间列用 TIMESTAMP | 不带时区存储 | 改为 TIMESTAMPTZ；数据迁移统一为 UTC |
| 大表 backfill 未分批 | 单条 UPDATE 全表 | 改为分批执行 + 可恢复策略 |
| 事务内调外部 API | 外部调用在事务块内 | 将外部调用移到事务外；先持久化意图，异步执行 |
| 迁移风险未分级 | 所有迁移同等待遇 | 按 Low/Medium/High/Critical 分级并执行对应要求 |
-- 约束和默认值一起定义
CREATE TABLE tasks (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
title TEXT NOT NULL CHECK (char_length(title) > 0),
status TEXT NOT NULL DEFAULT 'pending'
CHECK (status IN ('pending', 'completed')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 索引覆盖查询模式: WHERE status = X AND assignee_id = Y
CREATE INDEX idx_tasks_status_assignee ON tasks(status, assignee_id);
-- 零停机: 可空列 → 回填 → 加约束（三步迁移）
CREATE TABLE taskAssign (id TEXT, taskId TEXT, usr TEXT);
-- 无约束、缩写列名、无主键、无外键
ALTER TABLE tasks ADD COLUMN description TEXT NOT NULL;
-- 一次性 NOT NULL → 锁表 → 现有行无值 → 迁移失败
-- 无 DOWN 脚本 → 不可回滚
SELECT * FROM tasks;
-- SELECT * + 无 WHERE + 无索引
数据库工程完成：
迁移文件: <timestamp>_<name>.up.sql + .down.sql（或备份+补偿方案）
风险级别: Low / Medium / High / Critical
大表: 是/否 | 破坏性变更: 是/否 | staging 已验证: 是/否 | rollback 已测试: 是/否
Schema 变更: [新表 +约束数 | 新列 +约束 | 外键引用]
索引: [索引名 + 服务的查询模式 + 写入成本评估]
查询: N+1 [已修复/无] | EXPLAIN [Index/Seq Scan] | 延迟 [< 50ms]
完整性: 约束 [PK/FK/NOT NULL/CHECK/UNIQUE/DEFAULT] | 时间 TIMESTAMPTZ | 软删除 [deleted_at/is_deleted]
Backfill: [需要/不需要 | 分批策略 | 可恢复]（如有）
事务: [边界 | 并发控制: optimistic/row lock/none]（如有）