gordon-test-db

Purpose

Postgres test-database scaffolding for the Gordon platform. Provides fast per-test fresh DB clones by leveraging Postgres's CREATE DATABASE ... TEMPLATE ... — a pre-migrated template is built once per migrator fingerprint and cloned for each test invocation (~50–100 ms vs seconds for running migrations from scratch). Extracted from the legacy umbrella crate's test_support module on 2026-05-01 to break the diamond dependency between the contracts crate and gordon-migrate.

Version + status

1.1.1 — stable. No open epics. Used as a dev-dep by every Postgres-backed service.

Public surface

• test_db() — returns a fresh migrated TestDb per invocation (uses the bundled gordon_migrate::MIGRATIONS when the test-migrations feature is enabled). Panics loudly if the test Postgres is unreachable — silent skips are banned.

  let db = test_db().await.expect("test Postgres required — run make test-up");

• test_db_with_migrator(migrator: &Migrator) — same as test_db() but accepts an explicit sqlx::migrate::Migrator. Use this in gordon-migrate's own tests (the test-migrations feature would close a circular dev-dep).

• TestDb — handle holding the PgPool + cleanup hook.

• DbError — failure taxonomy: admin connection, template build, clone, migrate, drop.

• fingerprint_migrator() — deterministic hash of a migrator's source SQL, used as the template-DB cache key.

• noise_floor::WarnCounter (1.1.0) — tracing_subscriber::Layer that counts WARN + ERROR events and asserts an idle window stayed quiet. Canonical replacement for the five bespoke copies previously spread across the service crates.

• nats::test_nats() (1.1.0, feature nats) — panic-loud test NATS client connection. Reads GORDON_TEST_NATS_URL, defaults to nats://localhost:4223.

Feature flags

Feature	Activates
test-migrations	Zero-argument test_db() that bakes in gordon_migrate::MIGRATIONS. Pulls gordon-migrate as an optional dep.
nats	nats::test_nats() helper. Feature-gates async_nats so Postgres-only consumers don't pull the NATS + TLS stack.

Dependencies of note

• sqlx — admin connection, template clone, migration runner.
• gordon-migrate (optional, test-migrations feature) — bundled migrator.
• async-nats (optional, nats feature).
• No runtime gordon-* deps in the default surface. This crate must never depend on gordon-contracts, gordon-platform, gordon-exchange, or any other gordon-* service crate. It is a dependency-graph leaf by design.

Invariants

• Dev-deps only. Production code in any consumer service must not import this crate. Enforced by convention ([dev-dependencies] placement in every consumer Cargo.toml).
• No runtime gordon-* deps. Breaking this rule restores the diamond dependency that the extraction was intended to cut.
• Single source of truth for cloning. Every gordon-* test that wants a fresh DB goes through this crate. No service implements its own clone path.
• Panic-loud, never silent-skip. test_db().await.expect("test Postgres required — run make test-up") is the only pattern. Silent-skip guards are banned workspace-wide (2026-04-19).
• Zero #[allow(...)].

Where it lives

• Repo: gordon-test-db/
• kellnr: https://kellnr.lepaux.com/crates/gordon-test-db (LAN-only)
• Not on crates.io.

Related

• gordon-migrate — owns the migrations/ directory; gordon-test-db applies the migrator but does not author migrations.