pg-aiguide
installs/mo · npmstarsforks
How to install pg-aiguide?
timescale/pg-aiguide
$git clone https://github.com/timescale/pg-aiguideAI-optimized PostgreSQL expertise for coding assistants
README.md
| 1 | # pg-aiguide |
| 2 | |
| 3 | **AI-optimized PostgreSQL expertise for coding assistants** |
| 4 | |
| 5 | pg-aiguide helps AI coding tools write dramatically better PostgreSQL code. It provides: |
| 6 | |
| 7 | - **Semantic search** across the official PostgreSQL manual (version-aware) |
| 8 | - **AI-optimized “skills”** — curated, opinionated Postgres best practices used automatically by AI agents |
| 9 | - **Extension ecosystem docs**, starting with TimescaleDB, with more coming soon |
| 10 | |
| 11 | Use it as: |
| 12 | |
| 13 | - **Agent Skills** via `npx skills` — works with Claude Code, Cursor, Codex, Gemini CLI, and 40+ other agents |
| 14 | - a **public MCP server** that can be used with any AI coding agent, or |
| 15 | - a **Claude Code plugin** optimized for use with Claude's native skill support. |
| 16 | |
| 17 | ## ⭐ Why pg-aiguide? |
| 18 | |
| 19 | AI coding tools often generate Postgres code that is: |
| 20 | |
| 21 | - outdated |
| 22 | - missing constraints and indexes |
| 23 | - unaware of modern PG features |
| 24 | - inconsistent with real-world best practices |
| 25 | |
| 26 | pg-aiguide fixes that by giving AI agents deep, versioned PostgreSQL knowledge and proven patterns. |
| 27 | |
| 28 | ### See the difference |
| 29 | |
| 30 | https://github.com/user-attachments/assets/5a426381-09b5-4635-9050-f55422253a3d |
| 31 | |
| 32 | <details> |
| 33 | <summary>Video Transcript </summary> |
| 34 | |
| 35 | Prompt given to Claude Code: |
| 36 | |
| 37 | > Please describe the schema you would create for an e-commerce website two times, first with the tiger mcp server disabled, then with the tiger mcp server enabled. For each time, write the schema to its own file in the current working directory. Then compare the two files and let me know which approach generated the better schema, using both qualitative and quantitative reasons. For this example, only use standard Postgres. |
| 38 | |
| 39 | Result (summarized): |
| 40 | |
| 41 | - **4× more constraints** |
| 42 | - **55% more indexes** (including partial/expression indexes) |
| 43 | - **PG17-recommended patterns** |
| 44 | - **Modern features** (`GENERATED ALWAYS AS IDENTITY`, `NULLS NOT DISTINCT`) |
| 45 | - **Cleaner naming & documentation** |
| 46 | |
| 47 | Conclusion: _pg-aiguide produces more robust, performant, maintainable schemas._ |
| 48 | |
| 49 | </details> |
| 50 | |
| 51 | ## 🚀 Quickstart |
| 52 | |
| 53 | ### Agent Skills |
| 54 | |
| 55 | Install curated PostgreSQL best-practice skills for your AI coding agent: |
| 56 | |
| 57 | ```bash |
| 58 | npx skills add timescale/pg-aiguide --skill postgres |
| 59 | ``` |
| 60 | |
| 61 | Or pick individual skills interactively: |
| 62 | |
| 63 | ```bash |
| 64 | npx skills add timescale/pg-aiguide |
| 65 | ``` |
| 66 | |
| 67 | Works with Claude Code, Cursor, Codex, Gemini CLI, VS Code, and [40+ other agents](https://agentskills.io). |
| 68 | |
| 69 | For even deeper PostgreSQL knowledge, also add the [MCP server](#mcp-server) to give your agent semantic search over the official PostgreSQL, TimescaleDB, and PostGIS manuals. |
| 70 | |
| 71 | ### MCP Server |
| 72 | |
| 73 | For semantic search over PostgreSQL, TimescaleDB, and PostGIS documentation, add the **public MCP server**: |
| 74 | |
| 75 | [https://mcp.tigerdata.com/docs](https://mcp.tigerdata.com/docs) |
| 76 | |
| 77 | <details> |
| 78 | <summary>Manual MCP configuration using JSON</summary> |
| 79 | |
| 80 | ```json |
| 81 | { |
| 82 | "mcpServers": { |
| 83 | "pg-aiguide": { |
| 84 | "url": "https://mcp.tigerdata.com/docs" |
| 85 | } |
| 86 | } |
| 87 | } |
| 88 | ``` |
| 89 | |
| 90 | </details> |
| 91 | |
| 92 | Or it can be used as a **Claude Code Plugin**: |
| 93 | |
| 94 | ```bash |
| 95 | claude plugin marketplace add timescale/pg-aiguide |
| 96 | claude plugin install pg@aiguide |
| 97 | ``` |
| 98 | |
| 99 | #### Install by environment |
| 100 | |
| 101 | [](https://cursor.com/en/install-mcp?name=pg-aiguide&config=eyJuYW1lIjoicGctYWlndWlkZSIsInR5cGUiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9tY3AudGlnZXJkYXRhLmNvbS9kb2NzIn0=) |
| 102 | [](https://vscode.dev/redirect/mcp/install?name=pg-aiguide&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.tigerdata.com%2Fdocs%22%7D) |
| 103 | [](https://insiders.vscode.dev/redirect/mcp/install?name=pg-aiguide&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.tigerdata.com%2Fdocs%22%7D&quality=insiders) |
| 104 | [
