ADR-0002: No ORM — sqlc + pgx

Status

Accepted

Context

We need a database access strategy for PostgreSQL 16 that provides type safety, performance, and full control over queries without the abstraction leaks and N+1 pitfalls common in ORMs.

Decision

Use raw SQL with sqlc for compile-time type-safe Go code generation and pgx as the PostgreSQL driver. No ORMs (GORM, Prisma, etc.) are allowed anywhere in the codebase.

Consequences

Positive

• Full control over SQL — leverage PostgreSQL 16 features (CTEs, window functions, JSONB, etc.)
• sqlc catches query errors at code generation time, not runtime
• pgx provides connection pooling, LISTEN/NOTIFY support, and binary protocol
• No ORM abstraction leaks or unexpected N+1 queries

Negative

• Developers must write raw SQL (higher initial learning curve)
• Schema changes require manual migration files
• No automatic relation loading — must explicitly JOIN