Skip to content

Add database indexing best practices guide #22

@PAMulligan

Description

@PAMulligan

Description

Create a guide covering database indexing best practices within the Nerva/Drizzle ecosystem. Index design is one of the most impactful performance decisions in any API, and the framework should guide users toward good defaults.

Why

The pipeline generates Drizzle schemas with basic indexes, but users need guidance on when and how to add composite indexes, partial indexes, and covering indexes. Poor indexing is the #1 cause of slow APIs in production.

Acceptance Criteria

  • Create `docs/api-development/database-indexing.md`
  • Cover topics:
    • How to define indexes in Drizzle schema files
    • Single-column vs. composite indexes (with Drizzle syntax)
    • Unique indexes and constraints
    • Partial indexes for soft-delete patterns (`WHERE deleted_at IS NULL`)
    • When to use B-tree vs. GIN vs. GiST indexes
    • Index-only scans and covering indexes
    • Common anti-patterns (over-indexing, indexing low-cardinality columns)
    • How to use `EXPLAIN ANALYZE` to validate index usage
  • Include practical Drizzle ORM code examples
  • Reference the `performance-benchmarker` agent for automated analysis
  • Link from `docs/api-development/README.md`
  • CI passes

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions