name: postgresql-design description: 帮助Agent为项目进行PostgreSQL Schema设计、索引设计、查询设计，并提供场景化使用指南。当用户需要设计数据库表结构、优化查询性能、规划分区/复制方案时触发。 version: 1.0.0 metadata: clawdbot: emoji: "🐘" requires: anyBins: ["psql"] os: ["linux", "darwin"]

PostgreSQL 设计与使用助手

7w4.net提供免费和付费技能下载。

触发条件

当用户出现以下意图时激活本 Skill： - 设计 PostgreSQL 表结构 / Schema - PostgreSQL 索引优化 / 查询优化 - 分区方案 / 分表策略 - 逻辑复制 / 主从架构 - JSONB 半结构化数据设计 - "如何设计 xxx 的数据库"

设计流程（Agent 执行路径）

0. 版本检查 → 加载 references/version-major.md 对比用户版本，识别废弃项和重大变更。同时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本），后续设计过程中 Agent 从已加载的上下文中自主匹配深度特性
1. 需求分析 → 理解业务实体和关系
2. 概念设计 → ER模型，识别实体/关系/属性
3. 规范约束 → 加载 references/design-spec.md，确保命名/字段/索引符合规范
4. 逻辑设计 → 表结构DDL，含索引（B-tree/GIN/GiST/BRIN）、约束、注释
5. 物理设计 → 表空间/分区/填充因子/VACUUM策略
6. 使用指引 → 加载 references/usage-guide.md，给出场景化操作
7. 优化建议 → 加载 references/best-practices.md，给出性能建议
8. 模板参考 → 加载 references/patterns.md，匹配业务模板

快速参考

必备三字段

每张表必须包含：id (BIGINT GENERATED ALWAYS AS IDENTITY) / created_at (TIMESTAMPTZ NOT NULL DEFAULT now()) / updated_at (TIMESTAMPTZ NOT NULL DEFAULT now())

命名铁律

数据类型速查

PostgreSQL 特有须知

• 外键列不自动建索引 — 必须手动 CREATE INDEX，否则 DELETE/UPDATE 父表会锁子表全表
• 没有聚簇主键 — 行以插入顺序存储（堆表），CLUSTER 是一次性操作
• MVCC 产生死元组 — UPDATE/DELETE 留下死行，需设计 VACUUM 策略
• 不自建截断 — 插入 999 到 NUMERIC(2,0) 抛出错误，不会静默截断
• 自增 ID 有间隙 — 回滚/崩溃导致序列间隙是正常行为，不要尝试消除
• UNIQUE 允许多 NULL — 除非使用 NULLS NOT DISTINCT（PG15+）

索引类型速查

渐进式加载

详细内容按需加载 references/：

版本参考文档启用规则

1. 模块激活时 — 始终加载 references/version-major.md，Agent 需主动对比用户使用的 PostgreSQL 版本，若存在废弃项或重大变更，立即提示用户
2. 深度特性 Step 0 自动加载 — 版本检查时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本）。设计过程中 Agent 从已加载的上下文中自主检索匹配相关特性，用户无需指定版本号
3. 深度特性按大版本拆分，小版本持续追加 — 如 version-17.md 包含该大版本下所有小版本的设计级特性。更新时在文件中新增 ## X.Y.Z 版本节即可，不单开文件

硬规则

1. 设计规范内容来自权威资料（PostgreSQL官方文档/社区最佳实践），不编造
2. 所有外键列必须有索引 — PostgreSQL 不会自动创建
3. 所有表必须有主键，使用 BIGINT GENERATED ALWAYS AS IDENTITY
4. 优先使用软删除（deleted_at），物理删除需评估 GDPR/合规要求
5. 小数禁止用 FLOAT/DOUBLE，必须 NUMERIC
6. 时间必须用 TIMESTAMPTZ，不使用无时区的 TIMESTAMP
7. 表必须有 created_at 和 updated_at
8. JSON 数据必须使用 JSONB（非 JSON），高频查询字段上 GIN 索引
9. 单表超过 2000 万行或 10GB 时考虑分区（经验阈值，具体依查询模式调整）
10. 不推荐 SERIAL，使用 GENERATED ALWAYS AS IDENTITY

这个 Skill 在数据库设计指导方面质量良好，提供了清晰的命名规范、数据类型选择建议和索引策略。它包含的业务模板可以直接参考使用，版本兼容性考虑也比较周全。主要不足是文档之间有重复内容，阅读时容易感到冗余。另外缺少常见问题的解答，实际使用时可能需要自行摸索。总体而言，这是一个实用的设计参考工具，但在信息整合和实用性方面还有优化空间。