pg-aiguide

面向代码助手的AI优化PostgreSQL专业知识

pg-aiguide 帮助AI编码工具生成质量显著提升的PostgreSQL代码。它提供：

• 语义搜索，覆盖官方PostgreSQL手册（版本感知）
• AI优化的“技能”——由专家精选、带有明确观点的Postgres最佳实践，可被AI代理自动调用
• 扩展生态文档，首批支持TimescaleDB，后续还将提供更多

您可以将其用作：

• 通过 npx skills 提供的 代理技能 —— 兼容Claude Code、Cursor、Codex、Gemini CLI等40余款代理
• 作为 公共MCP服务器，可与任何AI编码代理配合使用；或
• 专为Claude原生技能支持优化的 Claude Code插件。

⭐ 为什么选择pg-aiguide？

AI编码工具生成的Postgres代码往往存在以下问题：

• 版本过时
• 缺少约束和索引
• 忽视现代PG特性
• 与实际生产中的最佳实践不符

pg-aiguide通过为AI代理提供深度且版本化的PostgreSQL知识库以及经过验证的最佳实践模式，有效解决了这些问题。

体验差异

https://github.com/user-attachments/assets/5a426381-09b5-4635-9050-f55422253a3d

🚀 快速入门

代理技能

为您的AI编码代理安装精选的PostgreSQL最佳实践技能：

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

或者以交互式方式选择单个技能：

npx skills add timescale/pg-aiguide

兼容Claude Code、Cursor、Codex、Gemini CLI、VS Code等，以及 40余款其他代理。

若需更深入的PostgreSQL知识，还可添加 MCP服务器，使您的代理具备对官方PostgreSQL、TimescaleDB和PostGIS手册的语义搜索能力。

MCP 服务器

对于 PostgreSQL、TimescaleDB 和 PostGIS 文档的语义搜索，可以添加 公共 MCP 服务器：

https://mcp.tigerdata.com/docs

{
  "mcpServers": {
    "pg-aiguide": {
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

或者也可以作为 Claude Code 插件 使用：

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

通过环境变量安装

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

codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide

{
  "mcpServers": {
    "pg-aiguide": {
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

gemini mcp add -s user pg-aiguide "https://mcp.tigerdata.com/docs" -t http

code --add-mcp '{"name":"pg-aiguide","type":"http","url":"https://mcp.tigerdata.com/docs"}'

code-insiders --add-mcp '{"name":"pg-aiguide","type":"http","url":"https://mcp.tigerdata.com/docs"}'

{
  "mcpServers": {
    "pg-aiguide": {
      "serverUrl": "https://mcp.tigerdata.com/docs"
    }
  }
}

💡 您的第一个提示

安装完成后，pg-aiguide 可以回答关于 Postgres 的问题或设计模式。

简单模式示例提示

创建一个用于存储用户名和唯一电子邮件地址的 Postgres 表模式。

复杂模式示例提示

您是一名资深软件工程师。您被分配了一项任务，需要为一家物联网设备公司生成一个 Postgres 模式。 这些设备在工厂车间收集环境数据。数据包括温度、湿度、压力等主要指标，以及其他因设备而异的测量值。每个设备都有一个唯一的 ID 和一个便于人类识别的名称。我们还希望记录数据采集的时间。对近期数据的分析包括根据测量值查找异常值和异常情况，以及针对特定设备进行临时性分析。历史数据分析则包括分析单个设备的历史数据，或统计所有设备在较长时间内的整体情况。

功能

文档搜索（MCP 工具）

• search_docs
  统一的搜索工具，支持跨多个文档源的语义（向量相似度）和关键词（BM25）搜索：
  • postgres - 官方 PostgreSQL 手册，按版本划分范围
  • tiger - Tiger Data 的文档（TimescaleDB 及其生态系统）
  • postgis - PostGIS 空间扩展文档

技能（AI 优化的最佳实践）

• view_skill
  公开经过精心挑选、带有明确观点的 PostgreSQL 最佳实践技能，由 AI 编码助手自动调用。

  这些技能提供以下方面的指导：

  • 模式设计
  • 索引策略
  • 数据类型
  • 数据完整性与约束
  • 命名规范
  • 性能调优
  • 现代 PostgreSQL 特性

🔌 生态系统文档

当前支持：

• TimescaleDB（文档 + 技能）
• PostGIS（文档）

即将支持：

• pgvector

我们欢迎为更多扩展和工具贡献内容。

🛠 开发

请参阅 DEVELOPMENT.md，了解：

• 如何在本地运行 MCP 服务器
• 如何添加新技能
• 如何添加新文档

🤝 贡献

我们欢迎：

• 新的 Postgres 最佳实践技能
• 更多的文档语料
• 搜索质量的提升
• 错误报告和功能建议

📄 许可证

Apache 2.0

pg-aiguide 快速上手指南

pg-aiguide 是一款专为 AI 编程助手优化的 PostgreSQL 专家工具。它能帮助 AI 生成更现代、性能更好且符合最佳实践的数据库代码（如自动添加约束、索引，使用 PG17 新特性等），解决 AI 生成代码过时或缺乏规范的问题。

环境准备

• 系统要求：支持 macOS、Linux 或 Windows（需安装 Node.js 环境）。
• 前置依赖：
  • 已安装 Node.js (推荐 v18+) 和 npm。
  • 正在使用的 AI 编程助手（如 Claude Code, Cursor, VS Code, Gemini CLI, Codex 等）。
• 网络要求：需要能够访问 mcp.tigerdata.com 以连接公共 MCP 服务器。

安装步骤

你可以根据使用的工具选择以下任一方式安装：

方式一：通过 Agent Skills 安装（推荐）

适用于 Claude Code, Cursor, Codex, Gemini CLI 等支持 npx skills 的代理。

安装全套 PostgreSQL 最佳实践技能：

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

或交互式选择特定技能：

npx skills add timescale/pg-aiguide

方式二：配置 MCP 服务器

适用于需要语义搜索官方文档（PostgreSQL, TimescaleDB, PostGIS）的场景。

1. 通用 JSON 配置

在你的 AI 工具配置文件（如 .cursor/mcp.json 或全局 MCP 配置）中添加：

{
  "mcpServers": {
    "pg-aiguide": {
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

2. 特定工具一键安装命令

• Cursor:

  # 或在 .cursor/mcp.json 中手动添加上述 JSON 配置
  

  

• VS Code:

  code --add-mcp '{"name":"pg-aiguide","type":"http","url":"https://mcp.tigerdata.com/docs"}'
  

• VS Code Insiders:

  code-insiders --add-mcp '{"name":"pg-aiguide","type":"http","url":"https://mcp.tigerdata.com/docs"}'
  

• Gemini CLI:

  gemini mcp add -s user pg-aiguide "https://mcp.tigerdata.com/docs" -t http
  

• Codex:

  codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide
  

• Claude Code (插件模式):

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

基本使用

安装完成后，直接在对话框中向 AI 助手提问或下达指令，pg-aiguide 会自动介入提供优化建议。

示例 1：简单表结构生成

提示词：

Create a Postgres table schema for storing usernames and unique email addresses.

预期效果： AI 将生成包含 NOT NULL 约束、唯一索引以及现代化语法（如 GENERATED ALWAYS AS IDENTITY）的健壮 Schema，而不仅仅是基础的 CREATE TABLE。

示例 2：复杂业务场景设计

提示词：

You are a senior software engineer. Generate a Postgres schema for an IoT device company collecting environmental data (temperature, humidity, pressure). Requirements:

1. Each device has a unique ID and name.
2. Support efficient time-series queries for recent anomaly detection.
3. Optimize for long-term historical statistics aggregation.
4. Use modern Postgres features and proper indexing strategies.

预期效果： 结合 pg-aiguide 的知识库，AI 将输出：

• 针对时序数据优化的分区表策略（如果适用）。
• 针对查询模式设计的部分索引（Partial Indexes）或表达式索引。
• 符合命名规范和数据完整性的外键约束。
• 针对 TimescaleDB 或原生 Postgres 的最佳实践建议。

注：该工具目前支持 PostgreSQL 官方文档、TimescaleDB 和 PostGIS 的语义搜索。