ADR 0005: Data access — Drizzle behind repositories, PGlite for tests

Status: Accepted

Date: 2026-07-19

Context

We need SQL visibility, module-owned schemas, RLS, and tests that run without Docker.

Decision

• Drizzle ORM is the default data-access library. Each module owns its schema files under modules/<id>/src/db and its migrations under modules/<id>/migrations.

• Repositories hide Drizzle from domain services; ORM entities never cross module boundaries (ports return domain types).

• Every repository method takes TenantContext and sets app.tenant_id on the transaction so RLS policies apply.

• Tests use PGlite (in-process Postgres) via @vercia/testing, so RLS, constraints and JSONB behavior are tested against real Postgres semantics without Docker. Production/dev uses the Postgres from docker-compose.yml or managed Postgres through the same Drizzle dialect contract.

Consequences

• pnpm test needs no services.

• Raw SQL is allowed inside repositories only, reviewed and covered by tests.