postgresql-table-design

postgresql-table-design 技能概览

这个技能能做什么

postgresql-table-design 技能用于帮助代理按照 PostgreSQL 的特性来设计或审查 schema，而不是给出泛泛的 SQL 建议。它重点关注那些最容易影响正确性和长期性能的设计决策：主键、范式化、可空性、默认值、数据类型、外键、索引，以及 PostgreSQL 特有的一些边界行为。

谁适合使用

如果你是开发者、数据工程师或数据库工程师，需要一份实用的 postgresql-table-design guide 来创建新表、审查现有 schema，或把产品需求转成以 PostgreSQL 为中心的设计，那么这个技能很适合你。

它实际解决的工作问题

大多数用户并不需要一堂数据库理论课。他们需要的是：让代理把一个粗略的领域模型，转成符合 PostgreSQL 习惯、可安全上线的表结构、约束和索引。这正是这个技能的价值所在：它能减少很多本可避免的错误，比如漏建外键索引、过度使用 UUID、选了不合适的数据类型，或者过早做反范式化。

它和通用 schema 提示词的区别

这个技能最核心的差异，在于它明确站在 PostgreSQL 的语境里给建议。源文件中的指导会明确推动你采用这些原则：

• 先做规范化，只有在有实测需求后才考虑反范式化
• 默认优先使用 BIGINT GENERATED ALWAYS AS IDENTITY 作为主键
• 常见场景下优先选择 TIMESTAMPTZ、NUMERIC、TEXT 和 BIGINT
• 对外键列显式建立索引
• 理解 PostgreSQL 的行为细节，例如未加引号标识符会转为小写，以及可空列配合 UNIQUE 时的表现

最适合与不适合的场景

当你想要一套实用的 postgresql-table-design for Database Engineering 工作流时，就该用这个技能。它非常适合 OLTP 风格的应用 schema、关系型数据建模和 schema 审查。反过来，如果你的核心问题是 ETL 编排、分析建模，或与表设计无关的 DBA 运维工作，它就没那么对口。

如何使用 postgresql-table-design 技能

postgresql-table-design 的安装位置与接入方式

这个技能位于 wshobson/agents 仓库中的 plugins/database-design/skills/postgresql。如果你的代理平台支持加载 GitHub 托管的技能，添加该仓库后选择 postgresql 技能即可。常见安装方式如下：

npx skills add https://github.com/wshobson/agents --skill postgresql

如果你的环境使用的是其他 skill loader，就把它指向这里：
https://github.com/wshobson/agents/tree/main/plugins/database-design/skills/postgresql

先读这个文件

先看：

• SKILL.md

这个技能的内容高度集中在一个文件里。在这个技能路径下看不到额外的辅助脚本或参考目录，所以大部分有效信息都在主文档中。这对快速上手是好事：读仓库的成本低，但也意味着它提供的完整示例会比那些“重型”技能更少。

这个技能需要什么输入

要让这个技能发挥最好效果，你需要提供明确的 schema 意图，而不是只说一句“帮我设计数据库”。高质量输入通常包括：

• 实体和它们之间的关系
• 预期的读写模式
• 唯一性规则
• 哪些字段可空、哪些是必填
• 金额、时间、标识符的语义要求
• 规模预期
• 关联行的更新/删除行为

如果没有这些信息，代理依然可以起草 schema，但索引和约束的选择通常会比较泛。

如何把模糊目标改写成强提示词

弱提示词：

• “Design PostgreSQL tables for an ecommerce app.”

更强的提示词：

• “Use the postgresql-table-design skill to design PostgreSQL tables for an ecommerce app. Entities: users, products, carts, orders, order_items, payments. Expected queries: list orders by user and date, fetch open cart by user, filter products by category and price. Money must be exact. All event times should preserve timezone. Users may have multiple addresses. Orders are immutable after payment except status fields. Recommend PKs, FKs, nullability, defaults, unique constraints, and indexes, then explain any denormalization you reject.”

这样的提示词能给技能足够多的信号，让它真正用上自己的核心规则。

这个技能通常会优先优化什么

从源文件的指导来看，这个技能通常会把设计引向：

• 先做规范化 schema
• 除非有明确理由，否则优先使用整数型代理主键，而不是 UUID
• 显式为 FK 建索引
• 对金额使用精确数值类型
• 使用带时区的时间戳
• 相比炫技式的一次性设计，更偏好保守、可维护的默认方案

如果你的系统需要完全相反的权衡，务必在提示词里明确说明。

postgresql-table-design 的实用工作流

一个好用的 postgresql-table-design usage 流程通常是：

1. 先描述业务域和主要查询路径。
2. 让它先给出包含表、列、约束和索引的初始 schema。
3. 重点审查输出中的主键选择、外键索引、可空性和数据类型。
4. 再要求它生成 DDL。
5. 最后再来一轮，专门聚焦查询模式和迁移风险。

相比一开始就直接要 SQL，这套顺序通常能把这个技能的价值发挥得更充分。

仓库里哪些线索在实战中特别重要

源文件里明确写了一些 “gotchas”，这一点很关键，因为很多通用提示词会漏掉 PostgreSQL 特有的行为。尤其当代理提到下面这些点时，要特别留意：

• 未加引号名称的小写标识符行为
• UNIQUE 与可空列的组合
• 精度和长度溢出的行为
• 外键不会自动建立索引

这些细节往往直接影响生产环境里的真实结果。

能明显提升输出质量的提示词要素

如果适用，建议把这些要求直接写进提示词：

• “Use snake_case identifiers only.”
• “Prefer BIGINT GENERATED ALWAYS AS IDENTITY unless you justify UUID.”
• “Index all FK columns unless there is a clear exception.”
• “Use TIMESTAMPTZ for event times.”
• “Use NUMERIC for monetary values.”
• “Call out where NOT NULL and DEFAULT should be applied.”

这些要求和技能本身的原生指导是一致的，因此代理更容易在第一稿就给出干净、靠谱的设计。

需要尽早决定的约束与权衡

在真正依赖输出之前，先想清楚这些问题：

• 你需要的是对外暴露/全局唯一的 ID，还是简单的本地主键？
• 你是在优化写入简单性，还是读取速度？
• 是否允许任何形式的反范式化？
• 可空字段到底表示“未知”、“不适用”还是“尚未采集”？
• 你是否需要精确的小数计算？

这些选择会直接决定这份 postgresql-table-design guide 产出的 schema，究竟是适配你的系统，还是只是“看起来正确”。

什么时候该让它做审查，而不是从头设计

这个技能也很适合做 reviewer。如果你已经有 DDL，可以让代理：

• 找出缺失的 FK 索引
• 标记不理想的数据类型选择
• 检查可空性和默认值
• 质疑过早的反范式化
• 指出 PostgreSQL 特有的正确性风险

如果你正在评估是否值得接入这个技能，这通常是最快的验证方式：直接拿自己的代码库来跑一轮。

postgresql-table-design 技能 FAQ

这个技能只适合新 schema 吗？

不是。它既适用于从零开始设计，也适用于 schema 审查。在成熟系统里，它最高价值的用法往往是找出缺失索引、薄弱约束以及值得商榷的数据类型选择。

它比普通提示词好在哪里？

普通提示词也许能生成“看上去合理”的 SQL，但经常会漏掉 PostgreSQL 特有的行为和默认实践。postgresql-table-design skill 会让代理在规范化、主键选择、外键索引、金额与时间类型，以及常见 PostgreSQL gotchas 上立场更清晰。

postgresql-table-design 适合初学者吗？

适合，前提是你已经理解基本的关系型概念。这个技能足够实用、也足够有主张，能帮助初学者绕开常见坑，但它不能替代你真正去理解约束、索引和查询模式之间是如何相互作用的。

它会直接生成可用于迁移的 SQL 吗？

不一定。源内容更偏向设计思路，而不是某个迁移框架的具体写法。它可以帮助你起草 DDL，但你仍然可能需要根据 Prisma、Drizzle、Rails migrations、Django migrations 或纯 SQL 工作流去做适配。

什么情况下不该用这个技能？

如果你的问题主要是以下这些方向，建议跳过：

• 数仓 / 星型模型建模
• ORM 特定的代码生成细节
• 与表设计无关的数据库管理
• 以分区或扩展为核心的架构问题，此时更广义的 PostgreSQL 运维能力比表建模更重要

它覆盖高级 PostgreSQL 行为吗？

它涵盖了一部分更进阶、也更实用的细节，但它最强的价值仍然是有纪律的表设计，而不是穷尽 PostgreSQL 内核层面的所有知识。更准确地说，它是一份聚焦型的 postgresql-table-design guide，不是完整的数据库架构框架。

如何把 postgresql-table-design 技能用得更好

提供查询模式，不要只给实体名

想快速提高输出质量，最有效的方法就是把关键读写路径讲清楚。“Users 和 orders” 这种输入太弱；而 “Fetch recent orders by user, join order items, filter unpaid orders by status and created_at” 就强得多，因为它会直接影响索引和约束决策。

明确说明标识符策略

这个技能默认明显偏向整数 identity 主键。如果你的系统因为对外暴露、分布式生成或跨系统合并安全等原因必须使用 UUID，要一开始就讲明白。否则代理很可能会合理地把方案拉回 BIGINT，这未必符合你的架构前提。

告诉代理哪些地方必须“精确”

如果你没说明金额和时间的语义，输出质量往往会变弱。可以直接写：

• “All prices require exact decimal arithmetic.”
• “Audit and event timestamps must preserve timezone.”
  这会把技能引导到 NUMERIC 和 TIMESTAMPTZ，而这正是它最有实战价值的一组默认选择之一。

不要只要 schema dump，也要它解释约束理由

更好的提示词是：

• “Design the schema, then justify each PK, FK, unique constraint, NOT NULL, and index.”

这样你就能看出代理到底是在真正使用这个技能的设计逻辑，还是只是在输出一份通用表定义。

留意 postgresql-table-design 常见失败模式

即使用了这个技能，也要重点复查这些地方：

• 漏掉 FK 索引
• 可空列使用过多
• 本应使用更精确类型，却落成了 text 字段
• 缺乏依据的反范式化
• 出于习惯而不是需求选择了 UUID
• 在可空列场景下会失效的唯一性规则

这些往往是一稿输出最容易需要返工的地方。

第一稿之后一定要继续迭代

拿到初版设计后，可以继续追问这类问题：

• “What query paths are still under-indexed?”
• “Which columns should be NOT NULL but are not?”
• “Where would this schema create update anomalies?”
• “Which denormalizations should wait until measured performance data exists?”

这第二轮追问带来的质量提升，通常比一开始把提示词写得更长还明显。

面向 Database Engineering 团队，提升 postgresql-table-design 一致性

如果团队要统一使用，最好把提示词输入标准化。要求每次请求都必须包含：

• 领域实体
• 基数关系和生命周期规则
• 关键查询
• 数据保留需求
• ID 策略
• 金额和时间的精确性要求
• 预期行数增长

这样能让 postgresql-table-design skill 在不同 reviewer 和不同项目之间表现得更稳定一致。

在正式采用前，先用它审查一份现有 DDL

如果你正在判断是否要接入这个技能，最好的测试方式之一就是拿一份真实 schema 做审查。给它一组接近生产环境的表，并要求它只指出 PostgreSQL 特有的问题。如果它能抓到那些你的通用提示词一直漏掉的设计问题，那就已经很能说明：这个技能值得安装。