MCPInstall

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
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads postgres-optimization automatically when relevant.

  3. 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 Scan on large tables indicates a missing index
  • Nested Loop with high row estimates suggests missing join index
  • Sort without Index Scan means the sort is happening in memory/disk
  • Buffers: shared hit vs shared read shows 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 ANALYZE to 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 FULL during 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 ANALYZE run 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_statements enabled 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

View all →

devops-automation

rohitg00/awesome-claude-code-toolkit

CI/CD pipeline design with GitHub Actions, Docker, Kubernetes, Helm, and GitOps patterns

DevOps & Cloud267 installs

accessibility-wcag

rohitg00/awesome-claude-code-toolkit

Web accessibility patterns for WCAG 2.2 compliance including ARIA, keyboard navigation, screen readers, and testing

Frontend & Design225 installs

react-patterns

rohitg00/awesome-claude-code-toolkit

React 19 patterns including Server Components, Actions, Suspense, hooks, and component composition

Frontend & Design211 installs

database-optimization

rohitg00/awesome-claude-code-toolkit

Open the skill to read its SKILL.md instructions.

Data & Databases210 installs

api-design-patterns

rohitg00/awesome-claude-code-toolkit

REST API design with resource naming, pagination, versioning, and OpenAPI spec generation

Backend & APIs209 installs

websocket-realtime

rohitg00/awesome-claude-code-toolkit

Open the skill to read its SKILL.md instructions.

209 installs

Popular data & databases skills

View category →

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.

OfficialData & Databases462.2K installs

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

OfficialData & Databases393.5K installs

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.

OfficialData & Databases392.3K installs

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.

OfficialData & Databases390.8K installs

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.

OfficialData & Databases384.4K installs

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.

OfficialData & Databases378.9K installs