pg-aiguide
A Timescale-maintained PostgreSQL agent extension combining local best-practice skills with hosted MCP documentation search for PostgreSQL, TimescaleDB, and PostGIS.
Project overview
pg-aiguide is a PostgreSQL agent extension maintained in the Timescale organization. It combines locally loaded database best-practice skills with Tiger Data's hosted documentation-search MCP. Users can install only the PostgreSQL skill, install the complete Claude Code plugin, or connect the MCP endpoint separately from clients such as Codex. Its role is to give an agent more specific PostgreSQL, TimescaleDB, and PostGIS references before schema design, index selection, migration planning, or version-sensitive troubleshooting.
Core capabilities
Version-aware PostgreSQL documentation search
search_docs requires an explicit source and distinguishes PostgreSQL 14 through 18, PostGIS 3.3 through 3.6, and Tiger Data documentation.
Semantic, keyword, and hybrid search
semanticWeight 0 uses BM25, 1 uses a semantic vector, and intermediate values run both paths and merge rankings with RRF.
Database-focused skills
The postgres skill routes tasks to references covering schema design, PostGIS, pgvector, hybrid search, hypertables, and safe migrations.
Multiple agent integration paths
The repository documents Claude Code marketplace, npx skills, Codex MCP, and several editor installation or configuration options.
Installation and usage
Claude Code users can add the timescale/pg-aiguide marketplace and install pg@aiguide. The plugin loads local database skills and connects to Tiger Data's hosted documentation-search MCP.
Let an AI Agent install it
Send this prompt to Codex, Claude Code, or another AI agent that can work with your local environment.
Help me install pg-aiguide from https://github.com/timescale/pg-aiguide. First read README.md, .claude-plugin/marketplace.json, skills/postgres/SKILL.md, API.md, and LICENSE. Confirm that the current client is Claude Code and that access to GitHub and https://mcp.tigerdata.com/docs is allowed. Tell me that hosted searches send queries to Tiger Data and that semantic or hybrid searches also use OpenAI embeddings on the server according to the source. After I confirm, run exactly claude plugin marketplace add timescale/pg-aiguide and claude plugin install pg@aiguide. Then check that pg@aiguide and search_docs are visible, and perform a minimal PostgreSQL documentation search without credentials or private business information. Report the installation result, configuration changes, visible tools, and anything unverified. Ask before requesting credentials, connecting to a database, overwriting configuration, self-hosting, executing SQL, or expanding permissions.- Claude Code with plugin marketplace support
- Network access to GitHub and https://mcp.tigerdata.com/docs
- Approval to send documentation search terms to an external hosted service
claude plugin marketplace add timescale/pg-aiguide
claude plugin install pg@aiguide- 1Confirm the data boundary
Confirm that mcp.tigerdata.com is allowed and agree that search terms will not include credentials, private SQL, or business data. Evaluate self-hosting instead if the hosted boundary is unacceptable.
- 2Add the plugin marketplace
Run claude plugin marketplace add timescale/pg-aiguide in Claude Code to add the repository's aiguide marketplace.
- 3Install the pg plugin
Run claude plugin install pg@aiguide. The manifest combines repository skills with a hosted search endpoint whose MCP skills are disabled to avoid duplicate skills.
- 4Inspect capabilities and run a non-sensitive check
Confirm that the postgres skill and search_docs are visible, then ask a public documentation question for an explicit PostgreSQL version. Check for content and metadata without including project secrets.
After the two installation commands, confirm that pg@aiguide is enabled and that the pg-aiguide MCP search_docs tool is visible. Search one public PostgreSQL documentation question with an explicit version and no sensitive information. The minimal function check passes only if the tool returns results with content and metadata.
- v0.6.1 was the release version when this page was verified, but src/serverInfo.ts still reports 1.0.0. Record both rather than automatically upgrading or downgrading.
- If local guidance is enough, install the postgres skill first and add the MCP only when official documentation search is needed.
- Do not put database passwords, connection strings, customer data, or private SQL in a hosted search query.
- Self-hosting additionally requires a pgvector database, documentation ingestion, and an OpenAI API key.
Use cases
Design PostgreSQL tables and indexes
Load the schema-design references before checking data types, constraints, indexes, and partitioning against versioned official documentation.
Plan lower-risk database migrations
Use the migration skill to structure lock waits, timeouts, rollback, and staged validation while keeping production execution subject to database-owner approval.
Check pgvector, PostGIS, and TimescaleDB guidance
Start from a focused skill and use documentation search to verify syntax or limits for the relevant extension and version.
Assessment
pg-aiguide combines database-specific practices and versioned documentation search in one extension, with clear entry points for Claude Code, Codex, and generic Agent Skills. It is useful for design and verification, not as authorization to modify a production database automatically. The main adoption checks are the hosted-query boundary, the missing repository security policy, and the database and embedding infrastructure required for self-hosting.
Why it may be useful
- It is maintained in the Timescale organization with clear licensing, manifests, API documentation, and self-hosting guidance.
- It spans PostgreSQL, TimescaleDB, and PostGIS while distinguishing multiple documentation versions.
- It supports keyword, semantic, and hybrid search, and its database skills are divided into concrete tasks.
- The repository has a recent release, commits, and successful visible test and lint workflows.
What to know first
- Hosted search crosses the Tiger Data boundary and may also call OpenAI's embedding service.
- The repository has no SECURITY.md, and runtime service-version metadata differs from the release version.
- Self-hosting requires a database, ingestion pipeline, and embedding service, making it more operationally involved than a hosted connection.
- Installation, MCP calls, and real database scenarios were not tested in this review.
README
pg-aiguide
Overview
A Timescale-maintained PostgreSQL agent extension combining local best-practice skills with hosted MCP documentation search for PostgreSQL, TimescaleDB, and PostGIS. MCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.
Getting started
- Claude Code users can add the timescale/pg-aiguide marketplace and install pg@aiguide. The plugin loads local database skills and connects to Tiger Data's hosted documentation-search MCP.
- The Agent Skills path includes focused references for PostgreSQL schema design, PostGIS, pgvector, hybrid search, TimescaleDB hypertables, and migrations.
- The MCP search_docs tool covers PostgreSQL 14–18, PostGIS 3.3–3.6, and Tiger Data documentation, with semanticWeight choosing keyword, semantic, or hybrid search.
- After the two installation commands, confirm that pg@aiguide is enabled and that the pg-aiguide MCP search_docs tool is visible. Search one public PostgreSQL documentation question with an explicit version and no sensitive information. The minimal function check passes only if the tool returns results with content and metadata.
Configuration
claude plugin marketplace add timescale/pg-aiguide
claude plugin install pg@aiguide