Module event_store
event-store only.Expand description
Postgres-backed SendEventStore.
§Status
Implemented, and run rather than asserted: 107 of 107 gated tests pass
against a live PostgreSQL 17.10 — the 95 rules of event_store_conformance!,
the 5 of event_store_concurrency_conformance! at CONTENDERS = 64, the
model family, and this crate’s own six.
One of those 105 runs weaker than the rest, and it is named here: the
fixture declines READ_YOUR_OWN_WRITES, so ops_agree_with_the_model runs
its trailing model, whose rustdoc lists what it gives up. A condition here
judges every committed row and a read shows only rows below the frontier,
deliberately different sets — see What this store costs a caller on the
crate root — and the trailing model predicts over the first. The counts
above read 101 and 89 until the 0.2.0 pass. The family was 93 rules and
had been since before this crate cleared it, so both numbers were
arithmetic on a stale one; it is 95 now, because ES-27 gained the two rules
that check a condition item’s tags are AND-ed rather than keyed on the first.
The concurrency family is the one that matters most: it is the first time an adapter in this portfolio has cleared it against a store whose writers are not serialised, which is the whole reason this crate is in the tree.
The projection store beside this one is implemented too, and the crate carries
no #![allow(clippy::todo)] any more — it left with the last stub, which is
the contract it was written under.
§Cancellation
A dropped append future cannot be cancelled by this adapter, and the
batch may already have committed. ES-23 is [FROZEN] and obliges every
adapter to say which of its two outcomes it has; this is ours, and it is the
less comfortable one.
The mechanism is on_runtime, which is Handle::spawn(work).await. Dropping
the caller’s future drops only the JoinHandle. Tokio detaches a spawned
task rather than cancelling it, so the transaction underneath carries on: the
INSERT runs, the COMMIT runs, and there is nobody left to tell. Nothing
in this adapter observes the drop, so nothing can react to it.
A caller MUST NOT read a dropped append future as evidence either way —
not that it committed, and not that it did not. The resolution is ES-24’s:
reissue the identical batch. Event identity makes the reissue idempotent, so
the second attempt either lands (the first did not commit) or is refused as a
duplicate (it did), and both answers are true ones.
This is precisely the shape ES-23’s own Rejects: names, reached through
spawn rather than spawn_blocking. It is not happenstance-sqlite’s
answer and must not be described in its words: that adapter says there is
nothing to drop, because its append has no suspension point at all. Ours
has one, and what is on the other side of it keeps running.
§The schema
Authoritative in migrations/0001_event_log.sql, compiled in by
crate::migration::MIGRATION_1 and applied by crate::migration::apply.
It is not restated here: the SQLite adapter keeps its schema as a Rust
constant mirrored into a doc comment and needs a test comparing the two
against sqlite_master, because the copies drift. A file has no second copy
to drift from.
What is worth reading before the file: position carries no column
default and is not bigserial; the sequence is read explicitly at the one
INSERT that allocates; and each row stamps pg_current_xact_id() into an
xid8 column, which is the mechanism every read and head filter on.
position is deliberately not bigserial. That is the whole subject of
this module’s ES-10 note below: a serial column is nextval(), and
nextval() is where the invariant is lost.
§ES-10, and what this adapter pays for it
ES-10 says position order is visibility order: once a reader has seen
position P, nothing at or below P may appear later. A naive Postgres
adapter breaks it, because nextval() allocates outside the transaction — a
writer takes 99, a writer that started later takes 100 and commits first, and
a reader who conditioned on after: Some(100) never sees the 99 that would
have violated its boundary. There is no error, no rejected append and no
failing test; there is a read model that is correct about a state the
business forbids.
This adapter buys the invariant with xid8 + pg_snapshot_xmin, and the
choice was measured rather than preferred. ADR-0024 is the record. Each row
stamps pg_current_xact_id(); every read and head admit only rows below
pg_snapshot_xmin(pg_current_snapshot()), the frontier beneath which no
transaction can still be in flight. The mechanism does not deny that
nextval() allocates outside the transaction — it stops treating position
order as visibility order and moves the guard to the read side.
What that asks of this adapter’s types and its append path:
- Writers do not serialise at all, which is the property this crate
exists to have, and
SendEventStore::append’s signature is untouched. What the async boundary did force is the conditional path: underREAD COMMITTEDtwo writers racing one boundary both find no conflict and both win, so a conditional append runsSERIALIZABLE— whose SSI is optimistic and takes no locks, so disjoint boundaries still proceed in parallel — and retries a40001. Holding a write lock instead is the move this crate exists not to make. - The cost is read-side, and it is structural rather than incremental.
Every read gains the visibility predicate, and the predicate is composed
into the cursor’s
DECLAREinside oneREPEATABLE READtransaction and evaluated once. Not perFETCH: the frontier advances between chunks, and a per-chunk predicate lets rows appear beneath positions the caller has already been handed — ES-10’s own violation arriving through the read path while the write path was being fixed. headreports the frontier rather than the maximum position, so freshly committed events are invisible until the frontier passes them. That is a capability limit rather than a type error: the adapter compiles, and then read-your-own-writes does not hold.
The two numbers. Steady state, measured against this built adapter with the predicate removed as the paired baseline: the median ratio straddles 1.0 at every concurrency level with about a 20% spread, so no cost large enough to matter is measurable — and the arms that cost 16x and 30x would be unmissable at that precision. Staleness, which is the real bill: a median of 0.593 ms unloaded and 4,799 ms behind a five-second write transaction held anywhere on the cluster, against an unguarded arm unaffected by the same hold at 0.595 ms.
The alternative that lost, named once so it is not re-proposed. A
tag-keyed advisory lock is the cheapest rival — 0.935 of baseline at 64
writers, nearly free — and it lost on the invariant rather than on cost:
it buys a per-boundary property where ES-10 states a global one, which makes
AppendCondition sound and the projection checkpoint unsound. Ranking the
arms by throughput would have selected it. The two that serialise every
writer, a sequence table and a constant advisory lock, are correct and lost
on cost at 0.062 and 0.033.
What follows for a caller, and the crate does not soften it: head is a
frontier, read-your-own-writes does not hold and is not claimed, and the
staleness bound is the longest open write transaction on the cluster — which
a consumer neither controls nor can necessarily observe. The crate root
states that bill where a consumer meets it first.
references/adr/0024-position-visibility-mechanism.md carries the argument,
the losing arms and what each lost on, and the parts this decision inherits
rather than owns.
Structs§
- Postgres
Event Store - A Postgres-backed event store.