ADR-0004 — Ship store protocols and a conformance suite, not adapters¶
Status: Accepted
Context¶
approvo is invoked from a backend-for-frontend that already owns a database — Postgres, MongoDB, DynamoDB, CockroachDB, something. That service has opinions approvo cannot share: which migration tool runs DDL, how the connection pool is configured, where transaction boundaries sit, what the naming conventions are, whether calls are sync or async.
We considered shipping approvo.stores.postgres, approvo.stores.mongo,
etc. We started to, and deleted them. A bundled adapter:
- imposes a driver dependency (
asyncpg?psycopg? which version?), - fights the host app's migrations and pool,
- has to guess at transaction semantics,
- accumulates per-database bug reports and feature requests,
- rots, because the maintainers don't run every database in anger.
Decision¶
approvo ships no database adapters. It ships:
- Three protocols in
approvo.stores.base—EventStore,ProjectionStore,IdempotencyStore— each a handful ofasyncmethods, each with its invariants written down as MUST/SHOULD. - A conformance suite in
approvo.testing—EventStoreConformance,ProjectionStoreConformance,IdempotencyStoreConformance— that is the executable form of those invariants, including concurrency tests (N racingappends /reserves must yield exactly one winner).
You implement the protocols over your database, subclass the conformance suites with a fixture yielding a fresh store, and run pytest. Green means approvo's guarantees hold on your datastore.
approvo does not ship an in-memory reference implementation either.
Earlier versions did (approvo.stores.memory), but a store that is part
of the public API invites production use it was never hardened for — no
persistence, no multi-process coordination, silent data loss on restart —
and every doc example that imported it obscured how little code the
protocols actually require. The three protocols above are the only
storage-agnostic surface approvo ships; anything concrete lives either in
your own codebase or in the test suite that exercises it (see
Storage for a from-scratch worked example, and
approvo.stores.base for the full contract).
Consequences¶
- Zero database dependencies in
approvo's dependency tree. The only runtime dependency stayscryptography. - The integration burden is real: a first Postgres implementation is ~150 lines. The conformance suite makes it a bounded, verifiable task rather than a guess.
- The reference schema sketches in Storage are documentation, not code — they can't drift into being a half-maintained adapter.
- If a particular database's implementation turns out to be genuinely fiddly (a distinguished-name for conditional writes, say), that is a docs problem to solve in the open, not a matrix of adapters to maintain.
- A community adapter can live in its own package
(
approvo-postgres) without the core project owning its lifecycle. - Docs and this library's own tests implement the protocols with small,
local, dict/list-backed stores where a worked example is useful; those
are illustrative code, not something you
importfromapprovo.