Skip to content
Vinxi/Kernel THE BOOK OF RECORD

ADR-0004: SQLx + explicit migrations, no ORM

ADR-0004: SQLx over ORM for kernel persistence

Status: accepted

Decision

Vinxi uses SQLx and explicit SQL migrations for Postgres-backed adapters. The kernel does not use an ORM as its model source.

Rules

  • vinxi-kernel-core depends on ports, not SQLx.
  • vinxi-adapter-postgres maps SQL rows to kernel models.
  • SQL migrations are physical schema changes only.
  • Ontology/catalog changes are kernel Acts, not silent database migrations.

Rationale

Kernel data is not ordinary CRUD. It is log-heavy, versioned, bitemporal, provenance-aware, and plane-specific. Explicit SQL keeps atomicity, idempotency, indexes, JSONB, and PostGIS behavior visible.