用 pg-aiguide 写出更好的 Postgres

让 coding agent 设计一张 Postgres 表，得到的往往是看似合理的 SQL：约束缺失、没有索引、还在用旧版本 Postgres 的写法。Timescale 出品、2k 星的 pg-aiguide 从两层堵住这个缺口：一套精选的、有明确立场的 Postgres 最佳实践 skill 装在本地，外加一个对官方 PostgreSQL 手册做语义检索、且按版本圈定范围的 MCP 服务。

为什么这个 Skill 重要

skills 目录共有十一个 skill，覆盖完整的设计闭环：快速上手点名了 postgres 和 schema-exploration，另有 design-postgres-tables、design-postgis-tables、postgres-database-migration、postgres-hybrid-text-search、pgvector-semantic-search，以及 TimescaleDB 专属的 setup-timescaledb-hypertables、timescaledb-hyperfunctions、find-hypertable-candidates、migrate-postgres-tables-to-hypertables。README 列出了这些指引的覆盖面：探索既有 schema 与对象、schema 设计、索引策略、数据类型、数据完整性与约束、命名规范、性能调优、现代 PostgreSQL 特性。

MCP 层提供 search_docs 工具——语义（向量）与关键词（BM25）检索合一——覆盖三个来源：按版本圈定范围的官方 PostgreSQL 手册、TimescaleDB 及其生态的 Tiger Data 文档、PostGIS 文档。view_skill 工具把最佳实践 skill 开放给任何支持 MCP 的 agent。生态覆盖目前从 TimescaleDB（文档 + skill）和 PostGIS（文档）开始，pgvector 已列为即将支持。

安装

安装旗舰最佳实践 skill：

npx skills add timescale/pg-aiguide --skill postgres

要调查一个已有数据库，改为安装探索 skill：

npx skills add timescale/pg-aiguide --skill schema-exploration

或者从全部十一个 skill 里交互挑选：

npx skills add timescale/pg-aiguide

README 说明这些 skill 适用于 Claude Code、Cursor、Codex、Gemini CLI、VS Code 等 40+ 个 agent。想叠加文档检索，添加公共 MCP 端点 https://mcp.tigerdata.com/docs 即可——也可以跳过手动配置直接用 Claude Code 插件，它同时捆绑了 skill 与 MCP 连接：

claude plugin marketplace add timescale/pg-aiguide
claude plugin install pg@aiguide

实战：按 pg-aiguide 的既定规范设计表结构

1. 安装 postgres skill 后开一个会话。
2. 给 agent 一个具体的设计任务：

为工厂车间的 IoT 设备数据设计 Postgres 表结构：每台设备有唯一 id 和可读名称，
持续采集温度、湿度、压力等读数。要支持异常值排查和单设备历史分析。
请说明用到的约束、索引和命名规范的理由。

3. agent 依据 skill 的指引工作——约束、索引策略、命名规范、现代 PostgreSQL 特性——而不是凭默认习惯；因为你要求解释理由，它会说明每个选择。
4. 当设计问题需要查官方手册时，MCP 的 search_docs 工具会从按版本圈定的 PostgreSQL 文档里找答案，而不是依赖模型记忆。

接手一个既有数据库时，先跑 schema-exploration skill：README 将其范围限定为调查既有 PostgreSQL 数据库，这也是任何迁移任务之前更稳妥的第一步。

技巧

• 不带参数运行 npx skills add timescale/pg-aiguide 可以看到全部十一个 skill，按项目挑选——TimescaleDB 那组只有在你真的用 hypertable 时才需要。
• 这些 skill 是明确有立场的；与团队既有规范冲突时，把它当成一次评审讨论，而不是默默覆盖。
• MCP 服务是 TigerData 托管的公共端点；skill 本身是本地文件——按你的数据策略选择叠加哪一层。
• Codex 用户可以直接添加 MCP 服务：codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide。

何时不用这个 Skill

它只服务 PostgreSQL——MySQL 或 SQLite 项目需要各自的指引。如果团队已维护内部 schema 标准，这套有立场的默认值带来的冲突可能多于收益。文档检索层依赖第三方托管端点；若数据策略不允许，就停在本地 skill 层，接受更小的知识覆盖面。

查看 排行榜 了解更多 skill。