pg-aiguide

背景：当 AI 编程助手遇上 PostgreSQL

试想这样一个场景：你的团队引入了一个 AI 编程助手，让它帮写数据库迁移脚本。结果 AI 开局就写了个没有主键的表、用了 TEXT 类型存日期、漏了所有外键约束——不是 AI 不够聪明，而是它根本没有"见过"现代 PostgreSQL 的最佳实践。

这正是 pg-aiguide 试图解决的问题。

项目起源与行业背景

pg-aiguide 由时间序列数据库厂商 Timescale 旗下的 TigerData 团队开发和维护，于 2025 年 7 月开源。Timescale 本身就是 PostgreSQL 生态的核心贡献者，其 TimescaleDB 扩展在时序数据场景中应用广泛。团队在长期服务企业用户的过程中发现了一个痛点：AI 编程工具在生成 PostgreSQL 代码时，普遍存在知识陈旧、遗漏约束、忽视现代特性等问题。

pg-aiguide 应运而生，目标很明确——让 AI 编程助手在处理 PostgreSQL 任务时，能够像资深数据库工程师一样思考和行动。

核心能力：从"写 SQL"到"懂 Postgres"

pg-aiguide 提供了两套互补的机制，共同提升 AI 的 PostgreSQL 能力：

文档语义搜索（MCP Server）

项目部署了一个 MCP（Model Context Protocol）服务器，提供 search_docs 工具，支持在多种数据库文档中进行混合搜索（语义向量搜索 + BM25 关键词搜索，权重可调）。支持的文档来源包括：

• PostgreSQL 官方手册：覆盖 PG 14 ~ PG 18 的所有版本，搜索时指定版本即可获得版本特定的最佳建议
• Tiger Cloud / TimescaleDB 文档：来自 TigerData 的文档，针对时序数据库场景
• PostGIS 空间扩展文档：覆盖 3.3 ~ 3.6 各版本

搜索结果中，低权重 RRF（Reciprocal Rank Fusion）算法融合了语义相似度和关键词命中度，确保既能找到语义相近的概念，也能精确命中特定函数名或关键字。

AI 优化技能集（Skills）

MCP 工具是"查询"层面，而 Skills 则是"行动"层面。项目维护了一套经过精心编写的 PostgreSQL 最佳实践技能，涵盖：

• Schema 设计：design-postgres-tables 和 design-postgis-tables 技能，指导 AI 如何设计规范化的表结构
• 索引策略：何时用 B-tree、何时用 GIN/ GiST、表达式索引、局部索引的取舍
• TimescaleDB hypertable：如何识别适合转换为 hypertable 的表、如何迁移已有表
• 全文搜索：PostgreSQL 原生 tsvector/tsquery 的混合文本搜索配置
• pgvector 向量搜索：语义搜索的数据库实现方案

这些技能以结构化 Markdown（.mdc 文件）存储，供 AI agent 在执行数据库任务时自动调用。

技术架构：TypeScript + PostgreSQL + AI SDK

从代码结构来看，pg-aiguide 的架构清晰而务实：

服务端：TypeScript 编写，基于 @tigerdata/mcp-boilerplate 框架实现 MCP Server。使用 ai SDK（Vercel AI SDK）和 @ai-sdk/openai 调用 OpenAI Embedding 接口，将用户查询向量化后与文档向量库匹配。后端数据库存储文档向量和 BM25 索引，目前使用 PostgreSQL 原生的 pgvector（注意：向量存储实现在 ingest/ 目录下，而非 MCP 服务本身）。

数据导入（ingest/）：独立的 Python 工具，负责从源文档（PostgreSQL 官方文档、TimescaleDB 文档、PostGIS 文档）抓取内容、清洗、语义分块（chunking），最终写入 PostgreSQL 向量库。这是一个 ETL pipeline，使用 BeautifulSoup 解析 HTML，chunking 模块做语义切分。

搜索实现（src/apis/searchDocs.ts）：混合搜索的核心逻辑，RRF 融合语义搜索和 BM25 关键词搜索的结果。搜索参数支持指定数据库来源和版本号。

插件生态：项目原生支持 Claude Code 插件、Cursor MCP、VS Code MCP、Goose、Windsurf 等主流 AI 编程工具，通过 npx skills add 命令即可将 Postgres 技能注入到任意 AI agent 中。

部署体验：开箱即用的 Docker 方案

pg-aiguide 提供了完整的 Docker 部署方案：

• Dockerfile：基于 oven/bun:1.3.5 镜像，单阶段构建，打包 Bun 运行时和编译后的 TypeScript 代码
• docker-compose.yml：一键启动 MCP Server + TimescaleDB HA 实例（timescale/timescaledb-ha:pg18），包含数据库初始化脚本

对于只想使用技能而非自建 MCP Server 的用户，项目还提供了更轻量的接入方式——直接通过 npx skills add 安装到 AI agent，无需任何服务端部署。但需要注意：语义搜索功能依赖远程 MCP 服务器（https://mcp.tigerdata.com/docs），如需本地化部署则必须完整启动 docker-compose 环境。

局限与争议

尽管 pg-aiguide 大幅提升了 AI 的 PostgreSQL 能力，但其局限性也值得关注：

1. 向量数据库依赖外部服务：当前版本依赖远程 TigerData MCP 服务器，若需完全离线使用，需要自行搭建向量存储和搜索服务，部署复杂度上升
2. 文档版本更新滞后：PostgreSQL 每年一个大版本发布，文档的版本覆盖速度取决于社区贡献和维护节奏
3. 仅支持 PostgreSQL 生态：对于 MySQL、MongoDB、ClickHouse 等其他数据库，没有对应的解决方案

行业意义

pg-aiguide 代表了一个重要趋势——AI 编程助手的专业化垂直化。通用 AI 模型在专业领域的表现受限于训练数据的时效性和领域深度，而 pg-aiguide 通过实时检索最新文档和调用专家编写的技能，弥补了这一差距。

从数据来看，项目 README 中提到的对比测试显示，使用 pg-aiguide 后 Claude Code 生成的 Schema 约束数量增加了 4 倍、索引数量增加了 55%，且引入了 PG17 推荐的新特性。这个数字说明了垂直知识库对 AI 输出的质的提升。

未来，随着 pgvector 支持的加入，pg-aiguide 有望成为 PostgreSQL 场景下 AI 编程的"标配插件"，其"文档搜索 + 技能注入"的双轨模式也值得其他专业领域借鉴。