PostgreSQL Skill

This skill is the working reference for PostgreSQL 16, 17, and 18 (current baseline: PG16). Cross-version notes go back to PG14 where behavior changed; PG13 and earlier are end-of-life and out of scope. PG14 reaches end-of-life on 2026-11-12 — flag upgrade urgency when a user is on it.

The skill is provider-neutral: bare-metal/self-hosted, containers, and Kubernetes operators are all covered. Managed-service limitations are called out categorically ("most managed providers disable X") without naming or recommending any specific vendor.

Each topic lives in its own reference file under references/. SKILL.md routes a user question to the right reference; the reference contains the executable detail, version admonitions, and primary-source citations.

Usage Workflow

When this skill is loaded, follow these steps to answer the user's question:

1. Identify the topic. Match the user's question against the Routing Table below using the keyword column. For multi-topic questions (e.g. "the locking behavior of REINDEX CONCURRENTLY") select multiple files.
2. Load the matched reference file(s). Use the Read tool against references/NN-topic.md. Do not paraphrase from memory — the reference holds the authoritative version notes and source URLs.
3. Follow See Also. Each reference ends with a See Also section linking related files. Follow it for cross-cutting questions (e.g. a VACUUM question pulls in MVCC, autovacuum, and wraparound).
4. Answer using the file. Lead with the direct answer or code, then version notes via admonitions, then caveats, then citation URLs.
5. Never answer from memory alone when a reference file exists for the topic. The references are the source of truth for this skill; the model's training data is not version-specific enough.
6. Assume PG16 unless told otherwise. If the user does not state a version, answer for PG16 and add a one-line note for differences on PG17/PG18. Only ask the user which version they are on if the answer materially changes across supported versions (e.g. wraparound mechanics, planner statistics behavior, archivecommand vs archivelibrary).

[!NOTE]
When a Postgres question does not obviously match a single file, load these cross-cutting entry points first: references/102-skill-cookbook.md (symptom-driven recipes spanning multiple files), references/22-indexes-overview.md (index decision routing), references/56-explain.md (plan reading), references/64-system-catalogs.md (catalog introspection).

User Response Format

Structure every answer using this skill as follows:

• Lead with the direct answer or pattern. If a SQL snippet or psql command satisfies the question, put that first.
• Add version admonitions inline. Use > [!NOTE] PostgreSQL 17 for new-in-17 features, > [!WARNING] Removed/Deprecated for things gone (with the version they were removed in and the replacement).
• Call out managed-service limitations categorically when relevant. Phrase as "most managed providers disable X" — never name a specific provider.
• End with source links. Cite the official PostgreSQL docs pinned to the correct major version (e.g. https://www.postgresql.org/docs/16/sql-vacuum.html, not /docs/current/).
• For longer answers, use headers matching the reference file's section headings so the user can jump to the source.
• For version-sensitive answers, default to PG16 + add inline > [!NOTE] PG17 / > [!NOTE] PG18 deltas. Only ask the user to confirm version when the answer flips between supported majors.
• For any performance investigation document or slow-query guide, always include an explicit section explaining how to read EXPLAIN plans bottom-up: start at the deepest-indented leaf node (scans execute first), work upward through parents (joins, sorts, aggregates), reach the root last. Identify the first node where actual rows diverges 10× or more from estimated rows — that is the misestimate source; everything above it operates on bad cardinality.

Routing Table

Keywords are matched case-insensitively. A single file can match multiple keyword phrases.

Disambiguation Tips

Some terms route to multiple files — load both when in doubt.

Versioning & Provider Neutrality

• Target compatibility baseline: every SQL example must run on PostgreSQL 16 unless explicitly marked otherwise.
• Version-pin docs URLs. Cite https://www.postgresql.org/docs/16/..., not /docs/current/. The current alias moves with each annual release.
• Provider neutrality is mandatory. Never recommend a managed provider over another. When discussing managed-service limitations, phrase categorically ("most managed providers disable untrusted PLs"), not by name.

Sources

Primary documentation roots (re-fetch before citing in any reference file; version-pin URLs to the matching major):

• PostgreSQL 14 manual (cross-version notes only): <https://www.postgresql.org/docs/14/index.html>;
• PostgreSQL 15 manual (cross-version notes only): <https://www.postgresql.org/docs/15/index.html>;
• PostgreSQL 16 manual (default baseline): <https://www.postgresql.org/docs/16/index.html>;
• PostgreSQL 17 manual: <https://www.postgresql.org/docs/17/index.html>;
• PostgreSQL 18 manual: <https://www.postgresql.org/docs/18/index.html>;
• Per-version release notes: <https://www.postgresql.org/docs/release/>;
• Versioning + support policy: <https://www.postgresql.org/support/versioning/>;
• PostgreSQL Wiki: <https://wiki.postgresql.org/>;
• Source code mirror: <https://github.com/postgres/postgres>;