postgres-best-practices

A reference shelf for the Postgres database, with a page each on designing tables, making slow queries fast, backups, replication, security and version upgrades, so you go straight to the one that matches the problem in front of you.

LABSCO SUMMARY

A skill on Postgres.

What it covers:

schema design and indexing
query optimisation
migrations
the mistakes that only show up in production

Named reviewers, and a bar on machine-written advice.

The repository names two reviewers: Stas Kelvich, a Neon cofounder and long-time Postgres contributor, and Jonathan Katz, a PostgreSQL Core Team member.

The repository's stated policy sets out what it will accept:

a skill must be written by a person
anything a model can produce on demand is not worth encoding ahead of time
a model may review and test a skill, but not author it

Contributions are paid and the call for more is still open.

WHEN TO USE

SCOPE

USE FOR

Choose the right column types and indexes when designing a new table.
Diagnose a slow query by reading its EXPLAIN ANALYZE output.
Plan a major-version upgrade of Postgres with a pre- and post-checklist.
Set up read replicas or logical replication for high availability.
Size and configure PgBouncer connection pooling for a busy application.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (3)

Postgres Best Practices

Guidelines and best practices for working with Postgres, covering schema design, indexing, query optimization, and common pitfalls.

Supported Versions

This skill covers PostgreSQL 14 through 18. Version-specific features are tagged (e.g., [PG15+], [PG18+]); environment-dependent examples identify required privileges, extensions, or multi-node setup.

PostgreSQL provides 5 years of support per major version. Always run the latest minor release.

Version	Initial Release	End of Life
18	September 2025	November 2030
17	September 2024	November 2029
16	September 2023	November 2028
15	October 2022	November 2027
14	September 2021	November 2026

Source: postgresql.org/support/versioning

References

Area	Resource	When to Use
Schema Design	`references/schema-design.md`	Designing tables, choosing data types, normalizing, partitioning
Indexing	`references/indexing.md`	Choosing index types, composite indexes, partial/covering indexes
Query Optimization	`references/query-optimization.md`	Reading EXPLAIN ANALYZE, fixing bottlenecks, planner tuning
Query Patterns	`references/query-patterns.md`	CTEs, window functions, lateral joins, UPSERT, JSONB, anti-patterns
Performance Diagnostics	`references/performance-diagnostics.md`	pg_stat views, lock analysis, VACUUM, connection management
Logical Replication	`references/logical-replication.md`	Pub/sub replication, live migrations, CDC
Hot Standby	`references/hot-standby.md`	Streaming replication, read replicas, failover
Transaction Isolation	`references/transaction-isolation.md`	Isolation levels, lost updates, serialization failures, retry logic
Backup & Restore	`references/backup-restore.md`	pg_dump/pg_restore, pg_basebackup, PITR, recovery
Security & Roles	`references/security-roles.md`	Privileges, RLS, pg_hba.conf, authentication, SSL
Bulk Data Loading	`references/bulk-loading.md`	COPY patterns, ETL staging, optimizing large loads, batch ops
Connection Pooling	`references/connection-pooling.md`	PgBouncer config, pool modes, prepared statements, sizing
Major Version Upgrades	`references/major-version-upgrades.md`	pg_upgrade, logical replication migration, pre/post checklists

Local tool required

1 FOR YOU

01
Have a Postgres database to apply this to
These are reference guides for schema design, indexing, query tuning, replication, and backups, meant to be applied against a real Postgres database (local or hosted, e.g. Neon) that you already have running.

Listed as free: Connected services may require an account or charge fees.
Installation: One command — usually under 2 minutes.

This skill ships inside the Postgres Skills plugin.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add neondatabase/postgres-skills --skill "postgres-best-practices" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install as a Claude Code plugin

Typed inside the agent's own prompt, not in a terminal. The marketplace is called postgres-skills, which is the part after the @.

01

/plugin marketplace add neondatabase/postgres-skills

02

/plugin install postgres-best-practices@postgres-skills

What's inside

Files included with this skill.

View on GitHub

The repository is licensed under Apache-2.0 — use, modification, and redistribution are allowed under that license’s terms.

View the repository’s license file on GitHub →

A skill on Postgres.

Named reviewers, and a bar on machine-written advice.

Postgres Best Practices

Supported Versions

References

Local tool required

Install as a Claude Code plugin

What's inside

MCP keyword matches

MCP Toolbox for Databases

Notion MCP

CodeGraphContext

Butterbase