postgres-best-practices — Claude Code skill: Postgres guidelines
A skill that feeds your agent guidelines on Postgres schema design, indexing, query optimization, migrations and common pitfalls. Useful whenever it writes SQL or sets up a database.
npx skills add neondatabase/postgres-skills --skill postgres-best-practices -a claude-codeWhat postgres-best-practices does
The skill gives the agent a set of reference files for PostgreSQL 14 through 18. They cover schema design, indexing, query optimization, query patterns, performance diagnostics, logical replication, hot standby, transaction isolation, backup and restore, security and roles, bulk loading, connection pooling, and major version upgrades. The agent opens the file that matches the task at hand.
Version-specific features carry tags like [PG15+] and [PG18+]. Examples that depend on the environment name the privileges, extensions or multi-node setup they need, so check those before running one.
Install takes a single npx skills add command, and the skill lands in your platform's skills folder. It runs in Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode.
What it helps with
- design a table schema for a known workload
- pick the right index type for frequent queries
- read an EXPLAIN ANALYZE plan and find the bottleneck
- configure PgBouncer connection pooling
- plan a major version upgrade
Example prompts for the agent
- check the postgres-best-practices skill for the right index for this query
- review my table schema against postgres-best-practices
- how does postgres-best-practices say to set up PgBouncer for this service
How to install postgres-best-practices
1Skills CLI (Vercel)
npx skills add neondatabase/postgres-skills --skill postgres-best-practices -a claude-code2Manually: put the files in place
~/.claude/skills/postgres-best-practices/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/postgres-best-practices/
1Skills CLI (Vercel)
npx skills add neondatabase/postgres-skills --skill postgres-best-practices -a codex2Manually: put the files in place
.agents/skills/postgres-best-practices/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add neondatabase/postgres-skills --skill postgres-best-practices -a cursor2Manually: put the files in place
.cursor/skills/postgres-best-practices/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install neondatabase/postgres-skills postgres-best-practices2Manually: put the files in place
.github/skills/postgres-best-practices/SKILL.md1Skills CLI (Vercel)
npx skills add neondatabase/postgres-skills --skill postgres-best-practices -a gemini-cli2Platform CLI
gemini skills install https://github.com/neondatabase/postgres-skills --path skills/postgres-best-practicesManually: put the files in place
.devin/skills/postgres-best-practices/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add neondatabase/postgres-skills --skill postgres-best-practices -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about postgres-best-practices
How do I install postgres-best-practices in Claude?
Run npx skills add neondatabase/postgres-skills --skill postgres-best-practices -a claude-code. The skill lands at ~/.claude/skills/postgres-best-practices/SKILL.md.
What does postgres-best-practices do?
It hands the agent references on Postgres schema design, indexing, query optimization, migrations and common pitfalls. The agent pulls them in when writing SQL or setting up a database.
Which PostgreSQL versions are covered?
PostgreSQL 14 through 18. Version-specific features are tagged like [PG15+], and environment-dependent examples name the privileges and extensions they require.
Source text
SKILL.md · Apache-2.0
--- name: postgres-best-practices description: Best practices and guidelines for working with Postgres. Covers schema design, indexing strategies, query optimization, migrations, and common pitfalls. Use when writing SQL, designing database schemas, optimizing queries, or setting up a Postgres database. --- # 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](https://www.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 |
© neondatabase · Apache-2.0 · neondatabase/postgres-skills
