pg-aiguide: versioned Postgres knowledge for coding agents
MCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.
At a glance
- What is it?
- A Python MCP server plus a set of agent skills that feed PostgreSQL documentation and opinionated best practices into AI coding tools. Worth adopting if your agent keeps writing outdated Postgres; useless if your team already has an internal SQL standards document the agent can read.
- Who is it for?
- Adopt pg-aiguide if your agent writes Postgres schema and migration code and you have no in-repo style guide for it to read. Skip it if your Postgres usage is confined to an ORM that generates all DDL, or if your organization forbids sending prompts to a hosted MCP endpoint.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure mode pg-aiguide targets
Ask a general-purpose coding model for a Postgres schema and you tend to get something that parses. What you often do not get is a schema that a DBA would sign off on. The README lists the specific symptoms it is aimed at: code that is outdated, missing constraints and indexes, unaware of modern PG features, and inconsistent with real-world best practices. Those four items are the project's own framing, and they map onto a real pattern. A model trained mostly on pre-2019 blog posts will reach for serial instead of GENERATED ALWAYS AS IDENTITY, will skip NULLS NOT DISTINCT, and will rarely produce partial or expression indexes unless prompted. The intended user is an engineer who is already using an AI coding agent for application work and keeps hand-correcting the SQL it emits. It is not a migration tool, not a linter, and not a schema diff engine. It sits in the prompt path, between the agent and the model.
Two delivery mechanisms, one knowledge base
pg-aiguide ships in three shapes, and the distinction matters when you decide what to install. The first is Agent Skills, distributed through the npx skills CLI, which the README says works with Claude Code, Cursor, Codex, Gemini CLI, VS Code, and 40+ other agents. Skills are files placed into your agent's skill directory; they carry curated, opinionated Postgres guidance that the agent loads on its own. The second is a public MCP server at https://mcp.tigerdata.com/docs, which exposes semantic search across the official PostgreSQL manual, plus TimescaleDB and PostGIS documentation, with the README describing the PostgreSQL manual search as version-aware. The third is a Claude Code plugin that bundles both: the skills in the repository's skills directory and the hosted MCP endpoint. The mechanism is retrieval, not fine-tuning. The agent asks a question, the server returns relevant manual passages or skill text, and the model conditions its answer on that. Version-awareness matters here because PostgreSQL syntax and recommendations shift between major releases, and a retrieval layer that ignores the target version will happily hand you PG17 idioms for a PG12 cluster.
Installing the skills versus wiring the endpoint
The two installation paths are genuinely different in effort and in what they expose. For skills alone, the README gives npx skills add timescale/pg-aiguide --skill postgres for the curated Postgres set, or npx skills add timescale/pg-aiguide with no --skill flag to pick individual skills interactively. For the MCP server, you add a JSON block. The README's generic form is an mcpServers object with a pg-aiguide key whose url value is https://mcp.tigerdata.com/docs. Tool-specific commands are provided: codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide, and gemini mcp add -s user pg-aiguide "https://mcp.tigerdata.com/docs" -t http. Cursor takes the same mcpServers JSON in .cursor/mcp.json. OpenCode uses a different schema entirely, with a top-level mcp object, a type of remote, and a url field, placed in ~/.config/opencode/opencode.json or a project-level opencode.json; the README notes you then write "use pg-aiguide" in your prompts to invoke the tools. Claude Code has its own two-command path: claude plugin marketplace add timescale/pg-aiguide followed by claude plugin install pg@aiguide. Note the package name in that second command, pg@aiguide, which does not match the repository name and is easy to mistype.
What the README's own comparison actually shows
The repository's headline evidence is a video transcript in which Claude Code is asked to write an e-commerce schema twice, once with the Tiger MCP server disabled and once enabled, then compare the two files. The summarized result lists 4x more constraints, 55% more indexes including partial and expression indexes, PG17-recommended patterns, the use of GENERATED ALWAYS AS IDENTITY and NULLS NOT DISTINCT, and cleaner naming and documentation. Read that carefully before treating it as a benchmark. It is a single prompt, on a single task, evaluated by the same model that produced both outputs, with the comparison performed by the model rather than by a human reviewer or a test harness. The direction of the claim is plausible given what retrieval of the actual manual should do, but the numbers are not a measurement of anything repeatable. Anyone deciding on this basis alone is deciding on a demo. The more defensible claim in the material is structural: the agent gets access to versioned manual text and to a curated skill set, which is a different input than a model's training distribution.
The hosted endpoint is the real dependency
Every MCP path in the README points at a single URL: https://mcp.tigerdata.com/docs. That endpoint is operated by TigerData, the company behind TimescaleDB, and the repository does not document a self-hosted deployment path for the server. So the practical constraint is not the Apache-2.0 licence on the code, it is that retrieval traffic goes to a third party. For a team working on a public schema this is unremarkable. For a team whose prompts contain table names, column names, or fragments of a proprietary data model, it means schema details leave your network. The README does not describe a retention policy, an authentication mechanism, or a rate limit for that endpoint, and those are the questions to answer before rolling it out broadly. If the answer is no, the skills path remains available and is purely local file installation, but you lose the manual search, which is the part that adapts to your PostgreSQL version.
Where pg-aiguide is the wrong tool
The project is opinionated by design, and the README says so in the phrase curated, opinionated Postgres best practices. Opinionated means it will push conventions your team may not share: a particular approach to identity columns, indexing strategy, or naming. There is no described mechanism for overriding a skill's guidance with your own house style. If your organization has a written SQL standard, pg-aiguide will compete with it rather than defer to it, and the agent has no way to know which one wins. Second, the extension coverage is narrow. TimescaleDB is present, PostGIS appears in the MCP description, and the README's own phrasing is "with more coming soon", which is an admission that the long tail of Postgres extensions is not covered. If your stack leans on pgvector, Citus, or a less common extension, retrieval will not help with those specifics. Third, if your application never writes raw DDL because an ORM or migration framework generates it, the schema-quality problem this project addresses is largely already solved upstream, and you are adding a network dependency for marginal gain.
Alternatives and the difference in approach
The most direct alternative is to do nothing beyond what your agent already has, which for many teams means pasting relevant manual sections into the prompt by hand or maintaining a project rules file. That approach is free, fully local, and version-pinned by you, but it does not scale past a handful of recurring questions and it goes stale silently. A second alternative is a general documentation MCP server pointed at a locally mirrored copy of the PostgreSQL manual. That gives you the same retrieval pattern with no third-party endpoint and full control over which manual versions are indexed, at the cost of building and hosting the index yourself and getting none of the curated skill content. The difference between pg-aiguide and both is that pg-aiguide bundles the opinionated layer with the retrieval layer and hosts the retrieval for you. You are trading operational control for a maintained index and a set of skills someone else wrote. That trade is reasonable for a small team without a platform group. It is a harder sell for an organization that already runs internal documentation search.
Licence, releases, and what to check before adopting
The repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That covers the code in the repository. It does not automatically cover the content served by https://mcp.tigerdata.com/docs, and the README does not state terms for that endpoint or for the manual text it returns; the PostgreSQL manual itself has its own licensing, separate from this project. This is a description of what the licence file says, not legal advice, and the endpoint terms are worth confirming with TigerData directly. On maintenance, the release cadence visible in the material is v0.5.0 in April 2026, then v0.6.0 and v0.6.1 in early September 2026, roughly two weeks apart, with the last push to main on 2026-09-09. That is an active project, and the 0.x version numbers indicate the interface is not yet frozen, so a pinned skill set or a copied MCP configuration may need revisiting. The concrete first step is to run npx skills add timescale/pg-aiguide --skill postgres in a scratch directory, read the installed skill files, and confirm you agree with the conventions they push before letting an agent apply them to a real schema.
Editorial conclusion
Adopt pg-aiguide if your agent writes Postgres schema and migration code and you have no in-repo style guide for it to read. Skip it if your Postgres usage is confined to an ORM that generates all DDL, or if your organization forbids sending prompts to a hosted MCP endpoint. Verify first that https://mcp.tigerdata.com/docs is reachable from your network and acceptable under your data policy, then run npx skills add timescale/pg-aiguide --skill postgres and inspect the installed skill files before trusting them.
Community notes