
postgres-optimization
PostgreSQL optimization including indexes, query plans, partitioning, JSONB operations, and connection pooling
- Installs
- 194
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/rohitg00/awesome-claude-code-toolkit --skill postgres-optimization- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads postgres-optimization automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
PostgreSQL Optimization
Index Strategies
-- B-tree index for equality and range queries (default)
CREATE INDEX idx_orders_customer_id ON orders (customer_id);
-- Composite index (column order matters: equality columns first, range last)
CREATE INDEX idx_orders_status_created ON orders (status, created_at DESC);
-- Partial index (smaller, faster for filtered queries)
CREATE INDEX idx_orders_pending ON orders (created_at)
WHERE status = 'pending';
-- Covering index (avoids table lookup entirely)
CREATE INDEX idx_users_email_name ON users (email) INCLUDE (name, avatar_url);
-- GIN index for JSONB containment queries
CREATE INDEX idx_products_metadata ON products USING GIN (metadata);
-- GiST index for full-text search
CREATE INDEX idx_articles_search ON articles USING GiST (
to_tsvector('english', title || ' ' || body)
);
-- Concurrent index creation (no table lock)
CREATE INDEX CONCURRENTLY idx_large_table_col ON large_table (col);
Reading Query Plans
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT o.id, o.total, u.name
FROM orders o
JOIN users u ON o.user_id = u.id
WHERE o.status = 'shipped'
AND o.created_at > NOW() - INTERVAL '30 days'
ORDER BY o.created_at DESC
LIMIT 20;
Key things to look for in the plan:
Seq Scanon large tables indicates a missing indexNested Loopwith high row estimates suggests missing join indexSortwithoutIndex Scanmeans the sort is happening in memory/diskBuffers: shared hitvsshared readshows cache efficiency
Partitioning
CREATE TABLE events (
id BIGINT GENERATED ALWAYS AS IDENTITY,
event_type TEXT NOT NULL,
payload JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
) PARTITION BY RANGE (created_at);
CREATE TABLE events_2024_q1 PARTITION OF events
FOR VALUES FROM ('2024-01-01') TO ('2024-04-01');
CREATE TABLE events_2024_q2 PARTITION OF events
FOR VALUES FROM ('2024-04-01') TO ('2024-07-01');
-- Index on each partition (inherited automatically in PG 11+)
CREATE INDEX ON events (created_at, event_type);
Partition tables with more than 10M rows when queries consistently filter on the partition key.
JSONB Operations
-- Query nested JSONB fields
SELECT * FROM products
WHERE metadata @> '{"category": "electronics"}'
AND (metadata ->> 'price')::numeric < 500;
-- Update nested JSONB
UPDATE products
SET metadata = jsonb_set(metadata, '{stock}', to_jsonb(stock - 1))
WHERE id = 'abc';
-- Aggregate JSONB arrays
SELECT id, jsonb_array_elements_text(metadata -> 'tags') AS tag
FROM products
WHERE metadata ? 'tags';
Connection Pooling
# pgbouncer.ini
[databases]
app = host=localhost port=5432 dbname=app
[pgbouncer]
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 25
min_pool_size = 5
reserve_pool_size = 5
server_idle_timeout = 300
Use transaction-level pooling for web applications. Session-level pooling for apps that use prepared statements or temp tables.
Common Tuning Parameters
-- Check for slow queries
SELECT query, calls, mean_exec_time, total_exec_time
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 10;
-- Find unused indexes
SELECT indexrelname, idx_scan, pg_size_pretty(pg_relation_size(indexrelid))
FROM pg_stat_user_indexes
WHERE idx_scan = 0
ORDER BY pg_relation_size(indexrelid) DESC;
Anti-Patterns
- Creating indexes on every column instead of analyzing actual query patterns
- Using
SELECT *when only a few columns are needed - Not using
EXPLAIN ANALYZEto verify index usage - Storing large blobs in JSONB when a separate table with proper types is better
- Missing connection pooling (each connection uses ~10MB of server memory)
- Running
VACUUM FULLduring peak hours (locks the entire table)
Checklist
- Indexes match actual query patterns (check
pg_stat_statements) - Composite indexes ordered: equality, then sort, then range columns
-
EXPLAIN ANALYZErun on all critical queries - Partial indexes used for frequently filtered subsets
- Connection pooler (PgBouncer/pgcat) in front of PostgreSQL
- Table partitioning considered for tables over 10M rows
- Unused indexes identified and dropped
-
pg_stat_statementsenabled for query performance monitoring
FAQ
What does the postgres-optimization skill do?
PostgreSQL optimization including indexes, query plans, partitioning, JSONB operations, and connection pooling
How do I install postgres-optimization?
Run npx skills add https://github.com/rohitg00/awesome-claude-code-toolkit --skill postgres-optimization in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/postgres-optimization/ (personal) or .claude/skills/postgres-optimization/ (project).
Which AI agents can use postgres-optimization?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is postgres-optimization safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains postgres-optimization?
It is published by rohitg00 in rohitg00/awesome-claude-code-toolkit. It has 194 recorded installs.
More from rohitg00/awesome-claude-code-toolkit
devops-automation
rohitg00/awesome-claude-code-toolkit
CI/CD pipeline design with GitHub Actions, Docker, Kubernetes, Helm, and GitOps patterns
accessibility-wcag
rohitg00/awesome-claude-code-toolkit
Web accessibility patterns for WCAG 2.2 compliance including ARIA, keyboard navigation, screen readers, and testing
react-patterns
rohitg00/awesome-claude-code-toolkit
React 19 patterns including Server Components, Actions, Suspense, hooks, and component composition
database-optimization
rohitg00/awesome-claude-code-toolkit
Open the skill to read its SKILL.md instructions.
api-design-patterns
rohitg00/awesome-claude-code-toolkit
REST API design with resource naming, pagination, versioning, and OpenAPI spec generation
websocket-realtime
rohitg00/awesome-claude-code-toolkit
Open the skill to read its SKILL.md instructions.
Popular data & databases skills
supabase-postgres-best-practices
supabase/agent-skills
Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.
prisma-client-api
prisma/skills
Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
prisma-database-setup
prisma/skills
Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.
prisma-cli
prisma/skills
Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.
prisma-postgres
prisma/skills
Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.
prisma-driver-adapter-implementation
prisma/skills
Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.