/ 目錄 / 演練場 / pg-aiguide
● 社群 timescale ⚡ 即開即用

pg-aiguide

作者 timescale · timescale/pg-aiguide

將 PostgreSQL 專業知識接入你的編碼代理 — 在官方文件上進行語意搜尋,加上精選的最佳實踐技巧。

Timescale 的 pg-aiguide 既是 Claude 外掛,也是一個 MCP 伺服器。它提供了在 PostgreSQL/TimescaleDB/PostGIS 文件上進行語意搜尋的功能,以及精選的「技巧」(架構設計、索引、資料型別、效能)。據報在生成的架構中增加了 4 倍的約束條件和 55% 的索引。

為什麼要用

核心特性

即時演示

實際使用效果

pg-aiguide.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "pg-aiguide": {
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "pg-aiguide": {
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "pg-aiguide": {
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "pg-aiguide": {
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "pg-aiguide",
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "pg-aiguide": {
      "command": {
        "path": "uvx",
        "args": [
          "pg-aiguide"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add pg-aiguide -- uvx pg-aiguide

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: pg-aiguide

如何讓代理寫出生產級的 Postgres 架構

👤 啟動新服務的後端工程師 ⏱ ~20 min intermediate

何時使用: 你想要生成的 SQL 能夠真正通過程式碼審查。

前置條件
  • 新增 pg-aiguide MCP — 將用戶端指向 https://mcp.tigerdata.com/docs 或安裝 Claude 外掛
步驟
  1. 說明領域
    我需要一個多租戶 SaaS 的架構,包含組織、使用者、專案、邀請。在寫 SQL 之前,請查詢 pg-aiguide 了解架構設計和識別子最佳實踐。✓ 已複製
    → 代理引用 view_skill 的輸出
  2. 檢查約束條件 + 索引
    告訴我你新增的每個約束條件及其原因。有任何多餘的索引嗎?✓ 已複製
    → 每個索引的說明
  3. 檢查現代功能
    使用 search_docs 驗證你使用的是 GENERATED ALWAYS AS IDENTITY(而不是 SERIAL),並在適當的地方使用 NULLS NOT DISTINCT。✓ 已複製
    → 應用了現代習慣用法

結果: 具有合理的約束條件、正確的識別欄位和你可以為其辯護的索引的架構。

注意事項
  • 代理過度使用索引 — 寫入密集的表格速度變慢 — 要求工作負載感知的索引 — 告訴它預期的讀/寫比率
搭配使用: postgres

在讀取 EXPLAIN 計畫時如何獲得專家上下文

👤 最佳化緩慢查詢的開發人員 ⏱ ~15 min intermediate

何時使用: 你有 EXPLAIN ANALYZE 的輸出,但不知道什麼是正常的。

步驟
  1. 分享計畫
    [貼上 EXPLAIN ANALYZE] — 使用 pg-aiguide 識別每個節點的作用以及成本的典型原因。✓ 已複製
    → 逐個節點的診斷,引用文件
  2. 詢問索引建議
    根據計畫,提議一個索引變更。通過 pg-aiguide 驗證索引類型(BTREE vs BRIN vs partial)。✓ 已複製
    → 具體的 CREATE INDEX 及其說明

結果: 計畫已理解,變更通過文件獲得了辯護。

搭配使用: postgres

如何選擇正確的 TimescaleDB 超級表設定

👤 在 Postgres 上進行時間序列的團隊 ⏱ ~15 min advanced

何時使用: 新服務中的第一個超級表 — 有很多調整參數。

步驟
  1. 說明攝取形狀
    我將每秒攝取約 10k 行的 IoT 感測器資料,查詢是最後 24 小時和最後 30 天的彙總。請查詢 pg-aiguide 以了解 TimescaleDB 超級表區塊間隔的建議。✓ 已複製
    → 區塊間隔 + 壓縮原則的理由
  2. 草擬表格
    草擬 CREATE TABLE + create_hypertable + 壓縮原則。✓ 已複製
    → 完整的 DDL

結果: 為你的攝取速率調整的超級表配置。

搭配使用: postgres

組合

與其他 MCP 搭配,撬動十倍槓桿

pg-aiguide + postgres

查詢 pg-aiguide 以了解最佳實踐,然後通過 postgres MCP 實際應用它們

使用 pg-aiguide 為 orders.user_id 選擇正確的索引,然後通過 postgres MCP 在開發資料庫上應用它。顯示變更前後的 EXPLAIN ANALYZE。✓ 已複製
pg-aiguide + github

使用文件支持的推理進行架構遷移的程式碼審查

審查添加新表的 PR #4421。使用 pg-aiguide 標記任何偏離習慣性 PG 16 的選擇。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
search_docs query: str, product?: 'postgres'|'timescale'|'postgis', version?: str 查詢特定的功能、函式或設定 免費
view_skill skill: 'schema-design'|'indexing'|'data-types'|'performance' 在寫入架構之前應用最佳實踐指導 免費

成本與限制

運行它的成本

API 配額
託管端點 — 合理使用速率限制
每次呼叫 Token 數
每個搜尋結果 300-1500 個代幣
費用
免費
提示
使用 view_skill 以獲得廣泛的指導,只在需要特定引用時使用 search_docs。

安全

權限、密鑰、影響範圍

最小權限: 無 — 僅文件
憑證儲存:
資料出站: 你的查詢會被傳送到 mcp.tigerdata.com
切勿授予: 無需授予;無資料庫存取

故障排查

常見錯誤與修復

search_docs 返回過時的資訊

固定版本:search_docs(query, version='17') 用於 PG 17 特定內容。

連線到 mcp.tigerdata.com 失敗

檢查企業防火牆;回退到 Claude 外掛(本地)安裝。

驗證: curl -I https://mcp.tigerdata.com/docs
view_skill 返回通用輸出

精確指定技巧 slug — 未知的 slug 會回退到通用摘要。

替代方案

pg-aiguide 對比其他方案

替代方案何時用它替代權衡
postgres MCP你需要執行 SQL,而不只是讀取文件沒有精選的最佳實踐層
Supabase MCPSupabase 特定的專案管理Supabase 鎖定

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills