clawmates/skills/backend/postgres-index-selection.md

name, description, when_to_use, tags

name	description	when_to_use	tags
postgres-index-selection	Which index type to reach for — btree/gin/gist/brin/hash — and when partial or expression indexes beat a plain one.	You're adding an index or diagnosing a slow query in Postgres.	backend postgres performance

Postgres index selection (17)

Default to btree unless the data shape says otherwise.

btree

• Equality + range on scalar columns.
• Multi-column: leading column must be in the WHERE clause for the index to help. (a, b, c) helps WHERE a=? AND b=?, not WHERE b=?.
• Descending: rare — btree can scan in either direction, but ORDER BY x DESC with a mixed-direction multi-col query benefits from (a ASC, b DESC).

Partial indexes — huge wins

Any time a WHERE clause repeats across queries, a partial index is a smaller, faster index:

CREATE INDEX missions_running_idx
    ON missions (updated_at DESC)
    WHERE status IN ('running', 'pending');

The clawmates codebase leans on this heavily — see topology_runs_status_idx WHERE status = 'queued'.

Expression indexes

For computed lookups:

CREATE UNIQUE INDEX users_lower_email_idx ON users (lower(email));
-- Query MUST use the exact expression:
SELECT * FROM users WHERE lower(email) = lower($1);

GIN

• JSONB: CREATE INDEX foo_meta_gin ON foo USING gin (metadata jsonb_path_ops); — jsonb_path_ops is smaller + faster than default for @> queries. Use default when you also need ? / ?| / ?&.
• Arrays: CREATE INDEX skills_tags_gin ON skills USING gin (tags); — WHERE tags && ARRAY['rust'] becomes index-served.
• Full-text search: to_tsvector('english', body) with a GIN index.

GiST

• Geo (PostGIS): USING gist on geometry / geography columns.
• Range types: USING gist on tstzrange for "does this range overlap" queries.

BRIN

• Very large tables where the indexed column correlates with physical row order (append-only timestamps, sequential ids). 1/1000th the size of btree, works only for range scans.

Hash (rare)

• Equality-only, very high-cardinality, no range. Postgres 10+ hash indexes are WAL-logged + replicated so they're finally safe — but btree wins in most benchmarks. Reach for it only when profiling justifies.

Diagnosis flow

EXPLAIN (ANALYZE, BUFFERS, VERBOSE)
SELECT ...;

Read from bottom up. Watch for:

• Seq Scan on a hot table with a WHERE that should be indexed → missing index.
• Index Scan with Rows Removed by Filter > returned rows → wrong index; add a compound or partial.
• Bitmap Heap Scan with Recheck on lossy → index is being used but not tightly; check if partial would help.
• Sort with Method: external merge Disk → sort spills to disk; add index that provides the order.

Anti-patterns

• Indexing every column. Each index has a write cost (INSERT/UPDATE amplification). Prefer 1–2 well-chosen composites over 6 single-column indexes.
• Indexing a boolean without WHERE. CREATE INDEX foo_active_idx ON foo(active) is worthless; ... WHERE active = true is what you want.
• Trusting pg_stat_user_indexes.idx_scan = 0 without waiting a full billing cycle. Some indexes exist for the monthly report.