pg-aiguide: PostgreSQL Expertise for AI Coding
Supercharge AI coding tools with optimized PostgreSQL knowledge and best practices.
- Source repo
- timescale/pg-aiguide
- Stars
- ★ 1.9k
- Last updated
- 11d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 33/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers using Claude Code or Cursor who want to create robust PostgreSQL schemas for e-commerce or IoT applications.
- Not a fit if
- Teams that need fully offline use; the public MCP server is hosted by TigerData
- Teams working with extensions beyond PostgreSQL, TimescaleDB, and PostGIS
- Non-technical users unwilling to install Node.js and run CLI commands
- Source review
- 33/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
pg-aiguide is an MCP server and Claude Code plugin that helps AI coding assistants generate better PostgreSQL code. It provides semantic search across the official PostgreSQL manual (version-aware) and curated 'skills' covering schema design, indexing, data types, and more. It can be used as Agent Skills via npx, as a public MCP server, or as a Claude Code plugin. The project is licensed under Apache 2.0 and supports multiple AI tools including Claude Code, Cursor, Codex, and Gemini CLI.
pg-aiguide exposes MCP tools like search_docs for semantic and keyword search over PostgreSQL, TimescaleDB, and PostGIS documentation. It also provides view_skill to access curated best-practice skills. When installed, AI agents automatically use these tools to retrieve relevant docs and skills, resulting in SQL with more constraints, indexes, and modern features.
- Developers using Claude Code or Cursor who want to create robust PostgreSQL schemas for e-commerce or IoT applications.
- Developers using Codex or Gemini CLI who need quick access to PostgreSQL documentation without leaving the terminal.
- Teams integrating Visual Studio or VS Code and wanting MCP-based documentation directly in their IDE.
- Data engineers designing time-series databases with TimescaleDB and needing best practices for partitioning and indexing.
- Organizations standardizing AI development workflows and seeking a unified PostgreSQL knowledge base for all agents.
How do you install or deploy this agent?
For Agent Skills, run npx skills add timescale/pg-aiguide --skill postgres or npx skills add timescale/pg-aiguide for interactive selection. For MCP, add the URL https://mcp.tigerdata.com/docs to your MCP client configuration. For Claude Code plugin, run claude plugin marketplace add timescale/pg-aiguide and then claude plugin install pg@aiguide.
How do you use this agent?
After installation, simply ask your AI agent to design a schema or answer Postgres questions. For example, 'Create a Postgres table schema for storing usernames and unique email addresses.' The agent will automatically leverage pg-aiguide's documentation and skills to produce high-quality results.
What are this agent's strengths and limitations?
- Version-aware semantic search over official PostgreSQL docs ensures up-to-date knowledge.
- Curated skills automate best practices, leading to dramatically better SQL (e.g., 4x more constraints, 55% more indexes).
- Pluggable across many AI tools via Agent Skills and MCP protocol, with one-click install for Cursor, VS Code, etc.
- Open-source (Apache 2.0) and extensible for additional extensions like pgvector.
- Public MCP server is hosted by TigerData, introducing a third-party dependency for hosted deployments.
- Installation requires Node.js and CLI commands, which may be a barrier for non-technical users.
- Documentation coverage is limited to PostgreSQL, TimescaleDB, and PostGIS; other extensions are not yet supported.
How does this agent compare with similar options?
Compared to using AI coding tools without any PostgreSQL-specific enhancement, pg-aiguide provides a substantial quality boost in generated SQL, as evidenced by the repository's own demonstration.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| pg-aiguide: PostgreSQL Expertise for AI Coding This agent | 33 · Major gaps | CLIFree | ★ 1.9k | 11d ago | Python | ChatGPT · Codex · Claude Code |
| Grounded Docs MCP Server | 50 · Major gaps | CLIFree + model costs | ★ 1.8k | today | TypeScript | ChatGPT · Claude Code |
| Microsoft Learn MCP Server | 43 · Major gaps | MCP serverFree | ★ 2k | 1mo ago | TypeScript | ChatGPT · Codex · Claude Code · Claude.ai |
| Remnic Agent Memory | 85 · Good | CLIFree + model costs | ★ 227 | 3d ago | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: The repository does not provide explicit permission models, user confirmation mechanisms, data flow transparency, sensitive data handling, dependency security audits, external effects documentation, rollback mechanisms, or source attribution. All trust criteria are unsupported, hence scored 0.
Evidence shows: README and package.json descriptions are consistent, both pointing to PostgreSQL documentation search and skills provision, self-consistency scored 2. Dependencies are listed in package.json but no availability guarantees or locked versions, dependency availability scored 1. No failure messages or error handling documentation, failure messages scored 0.
Evidence shows: README clearly identifies target audience (AI coding assistants) and multiple usage scenarios (Agent Skills, MCP server, Claude plugin), audience and scenarios scored 2. Capability boundaries partially described (e.g., supported extensions), but no explicit limitations, capability boundaries scored 1. Trigger precision not detailed, only mentions skills used automatically, trigger precision scored 1. Environment fit good, supports multiple IDEs and CLIs, environment fit scored 2.
Evidence shows: README structure clear, includes quickstart, features, development sections, information architecture scored 2. Installation instructions detailed, covering multiple environments, install notes scored 2. Naming stability not explicit, but version number exists, naming stability scored 1. Example prompts and video provided, examples and FAQ scored 2. Known limitations not explicitly listed, only mentions pgvector coming soon, known limitations scored 1. License is Apache-2.0, license scored 2. Version number exists but no changelog, versioning and changelog scored 1. Maintenance responsibility not explicit, but contribution guidelines exist, maintenance responsibility scored 1.
Evidence shows: Output usability high, provides search and skills, output usability scored 2. Marginal value evident, provides AI-optimized skills, marginal value scored 2. Cost-benefit not quantified, cost-benefit scored 1.
Evidence shows: Claims in README (e.g., 4x constraints) not backed by verifiable tests or data, claim traceability scored 1. Cross-source corroboration limited, relies on README only, cross-source corroboration scored 1. Facts and inferences not clearly separated, fact-inference separation scored 1.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- No permission model or user confirmation mechanism provided; evaluate carefully before use.
- Dependencies not pinned, posing supply chain risk.
- Claims (e.g., 4x constraints) lack verifiable evidence.
- No rollback mechanism or data flow transparency documentation.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Full Changelog: https://github.com/timescale/pg-aiguide/compare/v0.6.0...v0.6.1View on GitHub ↗ -
Release notes excerpt
What's Changed * Update @tigerdata/mcp-boilerplate to 1.6.4 by @Askir in https://github.com/timescale/pg-aiguide/pull/131 * Update dependencies (includes boilerplate XSS fix) by @murrayju in https://github.com/timescale/pg-aiguide/pull/132 * chore(ingest): update python deps to clear all 44 Dependabot alerts by @murrayju in https://github.com/timescale/pg-aiguide/pull/133 * Resolve relative inline links to fully-qualified URLs during scrape by @arimu1 in https://github.com/timescale/pg-aiguide/pull/129 …View on GitHub ↗ -
Release notes excerpt
What's Changed * [AGE-430] Add PostGIS versioning (and combine source+version) by @gregsaab in https://github.com/timescale/pg-aiguide/pull/90 * Update secrets to ORG_AUTOMATION_TOKEN by @dsanroman96 in https://github.com/timescale/pg-aiguide/pull/91 * [CHORE] update lock file by @gregsaab in https://github.com/timescale/pg-aiguide/pull/92 * [CHORE] use non-prod instead of github's runners by @gregsaab in https://github.com/timescale/pg-aiguide/pull/93 * [CHORE] revert by @gregsaab in https://github.com/timescale/pg-aiguide/pull/94 …View on GitHub ↗