---
title: "Postgres: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/timescale-postgres/
description: "Timescale's postgres skill from pg-aiguide: a dispatcher that sends the agent to nine reference guides for schema exploration, table design, pgvector and hybrid search, TimescaleDB hypertables and schema migrations."
---

# Postgres: review, setup & limitations · Undominated.ai

> Timescale's postgres skill from pg-aiguide: a dispatcher that sends the agent to nine reference guides for schema exploration, table design, pgvector and hybrid search, TimescaleDB hypertables and schema migrations.

[← Explore all skills](/skills/)

DATABASES / Timescale

# Postgres

Timescale's postgres skill from pg-aiguide: a dispatcher that sends the agent to nine reference guides for schema exploration, table design, pgvector and hybrid search, TimescaleDB hypertables and schema migrations.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/timescale/pg-aiguide)

SOURCE REVIEW

 Reviewed 2026-10-21
 Evidence 13 linked sources
 Publisher Timescale
 Licence [Apache-2.0 ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/LICENSE)
 Revision 187be00d317a
 [Read what was—and wasn’t—checked ↓](#review)

“Use this skill for any PostgreSQL database work — table design, indexing, data types, constraints, extensions (pgvector, PostGIS, TimescaleDB), search, and migrations. …”

 [Timescale · upstream description ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - Timescale publishes it in timescale/pg-aiguide (frontmatter license Apache-2.0, author tigerdata; NOTICE reads "Copyright 2025 Timescale, Inc., d/b/a Tiger Data"), and the README prints a single-skill install line for it: `npx skills add timescale/pg-aiguide --skill postgres`.
- SKILL.md maps nine references to tasks, each ending in a bold line on when to use it (six begin "Use when", one "Use to" and two "Use for"): read-only schema exploration through pg_catalog, general and PostGIS table design, pgvector semantic search, BM25 plus pgvector hybrid search, hypertable setup, hypertable-candidate scoring, hypertable migration, and schema migrations.
- The referenced guides carry explicit stop points: schema exploration asks for approval before reading data-derived statistics or rows, and the hypertable migration guide tells the agent to ask the user before changing a primary or unique key.

### A good fit for

 - Explore an unfamiliar PostgreSQL database read-only through pg_catalog before writing a query
- Choose data types, constraints and indexes for new or changed PostgreSQL tables
- Set up pgvector semantic search, or BM25 plus pgvector hybrid search with reciprocal rank fusion
- Score existing tables for TimescaleDB hypertable conversion and plan the migration
- Test a schema migration on a database fork before applying it to production

### Weigh up before choosing

 - The skills/postgres directory last changed in a commit dated 2026-09-25; the pinned revision 187be00d is dated 2026-10-07.
- SKILL.md holds no SQL itself; the instructions are in the nine references it links, which the agent has to load for each task.
- Version floors are stated only in the referenced guides: six of the nine (PostGIS table design, pgvector search, hybrid search, hypertable setup, hypertable-candidate scoring and hypertable migration) declare "Requires PostgreSQL 15+"; the schema-exploration queries target PostgreSQL 18 and use catalog columns also present in PostgreSQL 14–17; pg_textsearch supports PostgreSQL 17 and 18.
- The hybrid-search guide says pg_textsearch is currently in prerelease and not yet recommended for production use.
- The hypertable migration guide includes DDL that drops and re-adds a primary key, converts the table with create_hypertable (which it notes locks the table), adds a columnstore policy, renames tables and, commented out, drops the old table; its checklist lists a scheduled maintenance window or a backup.
- The README's other routes install more than this skill: `npx skills add timescale/pg-aiguide` picks skills interactively, and the Claude Code plugin (`claude plugin install pg@aiguide`) uses the skills directory and the public MCP endpoint hosted by TigerData.
- Licence: Apache-2.0 in LICENSE, the frontmatter and the README; NOTICE names Timescale, Inc., d/b/a Tiger Data.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - skills/postgres/SKILL.md (whole file)
- README.md: usage routes, Agent Skills quickstart, MCP server, Claude Code plugin, licence
- LICENSE
- NOTICE
- skills/schema-exploration/SKILL.md, the target of references/schema-exploration/guide.md
- skills/migrate-postgres-tables-to-hypertables/SKILL.md: key changes, checklist, in-place and blue-green options
- skills/postgres-hybrid-text-search/SKILL.md: frontmatter, pg_textsearch note, extension setup
- skills/design-postgis-tables/SKILL.md: frontmatter
- skills/postgres-database-migration/SKILL.md: drop-column and backfill examples, fork-based and dump-based testing
- skills/pgvector-semantic-search/SKILL.md: frontmatter and core rules
- skills/setup-timescaledb-hypertables/SKILL.md: frontmatter and retention policy step
- skills/find-hypertable-candidates/SKILL.md: frontmatter
- skills/schema-exploration/references/overview.md: version note
- Repository tree at 187be00d: modes and targets of the entries under skills/postgres/references

### Our findings

 - The frontmatter declares no allowed-tools; SKILL.md only tells the agent which reference file to load for which task.
- Every entry under skills/postgres/references is a relative symbolic link (git mode 120000) into a sibling skill directory, for example design-postgres-tables.md -> ../../design-postgres-tables/SKILL.md and schema-exploration/guide.md -> ../../../schema-exploration/SKILL.md.
- The README prints `npx skills add timescale/pg-aiguide --skill postgres` on a line of its own; the frontmatter name of skills/postgres/SKILL.md is postgres.
- The schema-exploration guide works on the database connection already available to the agent and says not to change schema, data, roles or session-wide settings without authorization.

### Not established by this review

 - Not executed: it was not installed or run.
- Whether the skills installer copies the targets of the symbolic links under skills/postgres/references was not checked.
- No SQL from any reference was run and no database was connected.
- The public MCP endpoint at mcp.tigerdata.com was not called.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/README.md)

DOCUMENTED COMMAND

 npx skills add timescale/pg-aiguide --skill postgres Copy command ↗

Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.

 - Run the README's single-skill line `npx skills add timescale/pg-aiguide --skill postgres` in the target project; it selects the skill whose frontmatter name is postgres.
- The README's other lines install more: `npx skills add timescale/pg-aiguide` picks skills interactively, and `claude plugin marketplace add timescale/pg-aiguide` with `claude plugin install pg@aiguide` adds the Claude Code plugin.
- The README's MCP server at https://mcp.tigerdata.com/docs is a separate, optional addition for documentation search.

### Before you start

 - A PostgreSQL connection available to the agent for the task, within the schemas the user has authorized
- PostgreSQL 15+ for the six guides that declare it (PostGIS, pgvector, hybrid search and the three TimescaleDB guides); pg_textsearch needs PostgreSQL 17 or 18
- pgvector, pg_textsearch, PostGIS or TimescaleDB only for the references that use them

### Compatibility

Claude Code · Cursor · Codex · Gemini CLI · VS Code

### Implementation

SQL

### Guidance for SQL the agent runs on a connected PostgreSQL database

 - No allowed-tools are declared; SKILL.md tells the agent to load reference files from the skill.
- The schema-exploration guide tells the agent to use read-only pg_catalog queries on the connection already available, to ask for approval before pg_stats or row sampling, and not to change schema, data, roles or session-wide settings without authorization.
- The pgvector, hybrid-search and TimescaleDB guides include CREATE EXTENSION statements for vector, pg_textsearch, vectorscale and timescaledb.
- The hypertable migration guide includes ALTER TABLE … DROP CONSTRAINT and ADD PRIMARY KEY, create_hypertable, add_columnstore_policy, table renames and a commented-out DROP TABLE; it tells the agent to ask the user before changing a key, before dropping hypertable-to-hypertable foreign keys, and before dropping unused indexes.
- The hypertable setup guide includes add_retention_policy (365 days in its example) and tells the agent to ask the user or comment it out if the period is unknown.
- The schema-migration guide includes ALTER TABLE … DROP COLUMN and batched UPDATE backfills, testing on a provider fork that is deleted if the migration fails, and shell commands pg_dump, createdb and pg_restore to build a test copy.

### Cost model

Apache-2.0 skill text. The files read state no fee; the hybrid-search guide says pg_textsearch is available hosted on Tiger Cloud as well as for self-managed deployments, without prices.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [postgres SKILL.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres/SKILL.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres/SKILL.md Supports: upstreamDescription, whySelected[0], whySelected[1], bestFor, access.permissions, install.steps[0], limitations[1], review.findings
- [README.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/README.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/README.md Supports: install, compatibility, whySelected[0], limitations[5], limitations[6]
- [Apache-2.0 LICENSE at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/LICENSE) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/LICENSE Supports: license, limitations[6]
- [NOTICE at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/NOTICE) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/NOTICE Supports: license, whySelected[0], limitations[6]
- [schema-exploration SKILL.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/schema-exploration/SKILL.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/schema-exploration/SKILL.md Supports: whySelected[2], bestFor[0], access.permissions, install.prerequisites, limitations[2]
- [migrate-postgres-tables-to-hypertables SKILL.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/migrate-postgres-tables-to-hypertables/SKILL.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/migrate-postgres-tables-to-hypertables/SKILL.md Supports: whySelected[2], bestFor[3], access.permissions, install.prerequisites, limitations[2], limitations[4]
- [postgres-hybrid-text-search SKILL.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres-hybrid-text-search/SKILL.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres-hybrid-text-search/SKILL.md Supports: bestFor[2], access.permissions, access.cost, install.prerequisites, limitations[2], limitations[3]
- [design-postgis-tables SKILL.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/design-postgis-tables/SKILL.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/design-postgis-tables/SKILL.md Supports: install.prerequisites, limitations[2]
- [postgres-database-migration SKILL.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres-database-migration/SKILL.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres-database-migration/SKILL.md Supports: bestFor[4], access.permissions
- [pgvector-semantic-search SKILL.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/pgvector-semantic-search/SKILL.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/pgvector-semantic-search/SKILL.md Supports: bestFor[2], access.permissions, install.prerequisites, limitations[2]
- [setup-timescaledb-hypertables SKILL.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/setup-timescaledb-hypertables/SKILL.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/setup-timescaledb-hypertables/SKILL.md Supports: access.permissions, install.prerequisites, limitations[2]
- [find-hypertable-candidates SKILL.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/find-hypertable-candidates/SKILL.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/find-hypertable-candidates/SKILL.md Supports: install.prerequisites, limitations[2]
- [schema-exploration references/overview.md at 187be00d ↗](https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/schema-exploration/references/overview.md) Checked 2026-10-21 https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/schema-exploration/references/overview.md Supports: limitations[2]

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Supabase Postgres Best Practices ↗ Connects Postgres schema and query decisions to worked SQL examples, connection guidance and row-level security checks.](/skills/supabase-supabase-postgres-best-practices/)[### CockroachDB SQL ↗ Cockroach Labs skill that turns a natural-language request into CockroachDB SQL, applies the relevant rule files with 00-fundamental-principles.md first, and tells the agent to run EXPLAIN on every generated query when a cluster connection is available.](/skills/cockroachlabs-cockroachdb-sql/)[### dbt Documentation Maintenance ↗ Audits descriptions in a dbt manifest and drafts missing model or column documentation in the project’s existing style.](/skills/dbt-labs-maintaining-dbt-documentation/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
