claude-postgres-skills

Production Postgres survival skills for Claude Code. Six focused, task-triggered skills that put the right rule in front of Claude at the moment it writes SQL — CREATE INDEX CONCURRENTLY, timestamptz, FOR UPDATE SKIP LOCKED, short transactions — instead of letting it guess.

Distilled from Hatchet's Postgres Survival Guide by Alexander Belanger.

Why

The schema is the hardest thing to change after it ships, and the difference between a migration that locks your whole table and one that doesn't is a single keyword. These skills encode the hard-won rules — schema design, safe migrations, query performance, connection pooling, autovacuum/bloat, and advanced queue/partitioning patterns — so Claude applies them automatically while coding, not after the incident.

Skills

Skill	Use when
`designing-postgres-schemas`	Creating tables, choosing primary keys, column types, or reaching for `jsonb`
`writing-performant-queries`	A query is slow / seq-scanning, or writing SELECTs, JOINs, ORDER BY, indexes
`writing-safe-migrations`	Altering tables, adding indexes/constraints, or migrating a large live table
`managing-postgres-connections`	Configuring a pool, hitting connection limits, or connection storms
`tuning-autovacuum-and-bloat`	Writes outpace vacuum, autovacuum runs long, or tables/indexes bloat
`postgres-advanced-patterns`	Building a queue, batch writes, partitioning, or large-table data migrations

Install

As a plugin (recommended)

/plugin marketplace add pumarogie/claude-postgres-skills
/plugin install database-skill

Manual

Copy the skills into your Claude skills directory:

git clone https://github.com/pumarogie/claude-postgres-skills
cp -R claude-postgres-skills/skills/* ~/.claude/skills/

How it works

Each skill has a Use when… description. Claude reads those descriptions and loads the matching skill the moment your task fits — no manual invocation. Ask it to add an index to a big live table and writing-safe-migrations fires; ask it to build a job queue and postgres-advanced-patterns fires.

Example

You: Add an index on orders(customer_id) — the table has 40M rows and takes live traffic.

Claude (with writing-safe-migrations loaded): uses CREATE INDEX CONCURRENTLY so writes aren't blocked during the build, and notes it can't run inside a transaction block.

Without the skill, the obvious CREATE INDEX locks the table against every write until it finishes.

Evals

evals/ holds 18 cases (three per skill) and a two-arm runner that compares responses with and without the skills loaded, scored against per-case rubrics.

No improvement claim is published yet, deliberately. At one run per case the item-level noise floor and the measured effect are the same size, so the numbers cannot yet separate a real effect from sampling variation. evals/FINDINGS.md records what was measured, what it does and does not support, and what the design needs before any number here means something. Read it before citing a result.

Source

The original six skills were distilled from Hatchet's Postgres Survival Guide by Alexander Belanger, and much of the framing remains theirs.

Material added since draws on:

The PostgreSQL manual — lock levels, DDL behavior, pg_stat_statements, autovacuum parameters, and all version-specific claims.
The pgbouncer documentation — pooling modes and what breaks under transaction pooling.
Cybertec on tuning autovacuum.

License

MIT — see LICENSE.

Claude Postgres Skills

At a glance

README