docs: add database indexing best practices guide

[PAMulligan]

Summary

Adds docs/api-development/database-indexing.md, a reference guide for index design in the Nerva (Drizzle ORM + PostgreSQL) stack. Poor indexing is the most common cause of slow APIs in production. The pipeline generates a baseline (a B-tree on each foreign key and on created_at); this guide is the reference for going beyond it.

Topics covered

• Defining indexes in Drizzle — the pgTable index callback, naming convention, the generate/migrate workflow, and the CREATE INDEX CONCURRENTLY caveat
• Single-column vs. composite indexes — the leftmost-prefix rule and how column order decides what a composite serves
• Unique indexes and constraints — .unique() vs. uniqueIndex(), expression/case-insensitive uniqueness, and NULL handling
• Partial indexes for soft deletes — WHERE deleted_at IS NULL, tied to the existing notDeleted() helper, including partial unique indexes so a deleted user's email can be reused
• B-tree vs. GIN vs. GiST (plus BRIN) — with jsonb containment and pg_trgm trigram search examples
• Index-only scans and covering indexes — including the honest note that drizzle-orm@0.45.2 exposes no .include(), so a true INCLUDE covering index needs a custom-SQL migration
• Anti-patterns — over-indexing, redundant indexes, low-cardinality columns, unindexed foreign keys, and functions over indexed columns
• Validating with EXPLAIN ANALYZE — reading the plan, a before/after, and testing at realistic data volume

Every Drizzle code example is verified against the installed drizzle-orm@0.45.2 index-builder API.

Wiring

• References the performance-benchmarker agent for automated profiling and index recommendations
• Linked from docs/api-development/README.md (Performance section)

Notes

• Markdown-only change; the affected CI job is the lychee link check. All external links return 200 and all internal link targets were verified to exist.

Closes #22

🤖 Generated with Claude Code