Agent Native

postgres-best-practices

This skill provides guidelines and best practices for PostgreSQL 14-18, covering schema design, indexing, query optimization, replication, backups, security…

by NeonOfficial publisherNot reviewed

Identity proven by GitHub's verified organisation badge (neondatabase)

Agents
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, claude.ai and API
License
Apache-2.0 (permissive)
Pin
27fe45epinned Oct 9, 2026
Context cost
about 770 tokenswhen the skill loads
GitHub stars
48on neondatabase/postgres-skills
Scripts
None found

What it does

“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.”
The author's description, from SKILL.md

Generated summary from the skill's own text

This skill provides guidelines and best practices for PostgreSQL 14-18, covering schema design, indexing, query optimization, replication, backups, security, and common pitfalls. It helps agents write efficient SQL, design performant database schemas, diagnose performance issues, and manage Postgres deployments safely.

When to use it

  • Designing database schemas, choosing data types, or planning table structures
  • Writing or optimizing SQL queries and reading EXPLAIN ANALYZE output
  • Setting up replication, backups, security roles, or connection pooling
  • Diagnosing performance problems or planning major version upgrades

When not to

  • Working with non-PostgreSQL databases like MySQL or MongoDB
  • Seeking version-specific features for PostgreSQL versions below 14

Install

These commands install from the publisher's repository and need no account.

skills CLI

npx skills add neondatabase/postgres-skills --skill postgres-best-practices

Installs from the repository's default branch, which may have changed since the commit we checked.

GitHub CLI 2.90 or later

gh skill install neondatabase/postgres-skills postgres-best-practices@27fe45e0f71ea89a6eaf9ea4d2e4068957c81c26

Installs the commit we checked (27fe45e).

Copy by hand

Download the folder at 27fe45e and put it in .claude/skills/postgres-best-practices for Claude Code and in .agents/skills/postgres-best-practices for Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode.

Skill folder on GitHub at 27fe45e

Claude Code plugin

/plugin install neon@claude-plugins-official

The publisher's plugin in Claude's official marketplace. It may hold more than this skill, and we have not pinned it.

Copy for your agent

A prompt for any coding agent. It installs this skill from GitHub at the pinned commit, copies the files as they are, and runs nothing unless you ask.

Prompt

Install the agent skill "postgres-best-practices" by Neon.

Source, pinned to commit 27fe45e0f71ea89a6eaf9ea4d2e4068957c81c26:
https://github.com/neondatabase/postgres-skills/tree/27fe45e0f71ea89a6eaf9ea4d2e4068957c81c26/skills/postgres-best-practices

1. Download that folder at exactly this commit. Do not use the default branch.
2. Copy every file unchanged, keeping the folder structure, into .claude/skills/postgres-best-practices/ for Claude Code and .agents/skills/postgres-best-practices/ for Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode. Create the folders if they do not exist.
3. Do not edit the files, and do not run any script in the folder unless I ask you to.
4. When you are done, list the files you copied and where you put them.

Listing and checks: https://www.agentnative.dev/skills/neon/postgres-best-practices

SKILL.md at the pin

---
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     |

From neondatabase/postgres-skills at 27fe45e, shown as plain text under its license: Apache-2.0 (permissive). The license text is in LICENSE.

View SKILL.md on GitHub at 27fe45e

Files

14 files, 160 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.

Skill folder on GitHub at 27fe45e
All 19 skills from Neon

More from Neon

  • neon

    Neon is a cloud backend platform providing Postgres, auth, object storage, serverless functions, and an AI gateway with branching, zero-scale compute, and…

    Claude Code, Codex, Cursor +4 · about 8.5K tokens · pinned 6 days ago

  • neon-ai-gateway

    The Neon AI Gateway provides a single API endpoint and credential to access frontier and open-source LLMs from multiple providers (OpenAI, Anthropic, Google…

    Claude Code, Codex, Cursor +4 · about 4.9K tokens · pinned 6 days ago

  • neon-auth

    This skill adds Better Auth-based login to new apps using Neon's managed authentication system, where users and sessions live in a Postgres schema.

    Claude Code, Codex, Cursor +4 · about 2.9K tokens · pinned 6 days ago

  • neon-functions

    Neon Functions deploys long-running Node.js HTTP handlers to your Neon database branch, injecting DATABASE_URL and hosting stateful workloads like AI agents…

    Claude Code, Codex, Cursor +4 · about 11.9K tokens · pinned 6 days ago

  • neon-object-storage

    Neon Object Storage provides S3-compatible file storage that branches with your Neon Postgres database, keeping files and database rows in sync across…

    Claude Code, Codex, Cursor +4 · about 3.3K tokens · pinned 6 days ago

  • neon-postgres

    This skill guides agents on working with Postgres databases on Neon, covering connection setup, pooled vs direct connections, schema migrations, branching…

    Claude Code, Codex, Cursor +4 · about 4K tokens · pinned 6 days ago

All Data and databases skills

Related in Data and databases

  • prisma-8

    This skill helps agents work with Prisma 8, a contract-first data layer for TypeScript projects.

    by PrismaOfficial publisher

    Contains scripts

    Claude Code, Codex, Cursor +3 · about 3.5K tokens · pinned 6 days ago

  • supabase-postgres-best-practices

    This skill provides a comprehensive guide to Postgres optimization and best practices maintained by Supabase.

    by SupabaseOfficial publisher

    Claude Code, Codex, Cursor +4 · about 440 tokens · pinned 6 days ago

  • dsql

    This skill enables agents to build and manage Aurora DSQL, a serverless PostgreSQL-compatible distributed SQL database.

    by Amazon (AWS)Official publisher

    Contains scripts

    Claude Code, Codex, Cursor +3 · about 6.5K tokens · pinned 6 days ago

  • neki

    This skill guides agents on Neki, PlanetScale's distributed sharded Postgres system.

    by PlanetScaleOfficial publisher

    Claude Code, Codex, Cursor +4 · about 2K tokens · pinned 6 days ago

  • postgres

    This skill provides PostgreSQL best practices, optimization guidance, and operational knowledge across schema design, indexing, query patterns, and…

    by PlanetScaleOfficial publisher

    Claude Code, Codex, Cursor +4 · about 1.7K tokens · pinned 6 days ago

  • chdb-datastore

    This skill enables working with tabular data using a pandas-compatible API backed by ClickHouse for faster execution.

    by ClickHouseOfficial publisher

    Contains scripts

    Claude Code, Codex, Cursor +3 · about 1.2K tokens · pinned 6 days ago

The skills listed here are third-party software, collected from public GitHub repositories as a catalog of recent skills and provided as is. Agent Native does not write or control them and is not responsible for any harm, loss or damage caused by installing or using them. Labels and checks describe what we saw at one commit and are not a guarantee. Read a skill's files before you run it. Terms of use