Skip to content
CommonLayer
Documentation menu
On this page

ADR-0003: SQLx with runtime-checked queries and real-database tests

Status: Accepted (plan decision D3). Implemented.

Context

SQLx can check queries at compile time against a live database or against committed offline metadata (.sqlx/). With many engineers editing migrations in parallel, offline metadata would conflict constantly, and compile-time checking would make every build depend on a running database.

Decision

Use SQLx with runtime-checked queries (sqlx::query, query_as, query_scalar with string SQL) and exercise every query in integration tests with #[sqlx::test(migrator = "commonlayer_database::MIGRATOR")], which creates a fresh database per test from the embedded migrations.

Consequences

  • cargo build works without PostgreSQL. cargo test needs one: make up starts it, and DATABASE_URL in .env points at a database the harness uses only to create per-test databases.
  • A typo in SQL is found by a test, not by the compiler; coverage of queries by tests is therefore part of the definition of done for every Rust work package.
  • make db-check applies all migrations to an empty database twice to prove they apply and re-run cleanly.