Module projection_store
projection-store only.Expand description
Postgres-backed SendProjectionStore.
§The Batch question, and the answer this adapter had to reach
The port used to declare type Batch<'a> where Self: 'a, and the module
documentation on it justified the lifetime with “a transaction cannot
outlive its connection”. That is true of rusqlite::Transaction<'a>, which
borrows its Connection. It was not true here, and that was the finding
that fed PS-5: PgPool::begin hands back a
Transaction<'static, Postgres>, taking the PoolConnection by value and
returning it to the pool on drop. A pooled, networked driver with every
opportunity to hand back a borrowed handle chose to hand back an owned one.
PS-5 removed the parameter on that evidence, and the evidence stands. What did not stand is the binding this file then carried:
type Batch = sqlx::Transaction<'static, Postgres>; // and five `todo!()`That binding could not be discharged under the port as it then stood, and
no compiler said so. todo!() has type !, which coerces to everything,
so a skeleton type-checks against a signature nothing can implement — the
hazard the specification already names about skeletons in general, and that
this file demonstrated in particular. Three facts settled it at phase 10b:
beginwas total, synchronous and infallible. There was noResult, noawait, and no argument to fail on.sqlx’s only constructor for a transaction isTransaction::begin, which isasyncand fallible;Transaction’s fields are private, so the type cannot be assembled by hand.Pool::try_acquireis synchronous but yields aPoolConnection, andBEGINis still a round trip.ProjectionProbe::probe_writewas synchronous and infallible too, so even given a live transaction there was no point at which this adapter could issue a statement into it.
ADR-0060 recorded that finding as the reason the port stayed gated, and
ADR-0062 acted on it: begin and the probe seam are async and fallible
now, and the binding this file could not discharge is discharged one module
over, in live_projection_store. That store
is the far end of PS-2’s batch-shape axis and it passes the suite.
This store stays as it is. The batch is PostgresProjectionBatch: an
owned, Send, 'static list of parameterised statements, replayed inside
one transaction that commit and reset open for themselves — PS-4’s
deferred write set, the same shape happenstance-sqlite reaches by a
different route. It is the default an application reaches for: it holds no
connection while apply runs, and nothing reaches the server until commit.
Since ADR-0074 the live store is drivable by the typed runner too, and pays
a pooled connection held for each chunk to send statements as apply runs.
§What that costs, stated rather than discovered
READS_THROUGH_BATCH
is false. Nothing has been sent to Postgres while a batch is open, so there
is no pending server state to read through, and answering from committed
state is what PS-12 forbids by name — a projection doing get then set
inside one batch would read the value from before the batch began and lose
every increment after the first.
The consequence for a caller is real and is not hidden: a projection whose
apply must read what it has already written in the same batch cannot be
written against this adapter. A shadow map inside the batch would buy a green
batch_reads_reflect_pending_writes about a second source of truth Postgres
never sees, and is rejected on the record for that reason.
§What this settled about PS-2, and what settled it back
PS-2 is [FROZEN] and names a live-transaction adapter as the far end of the
batch-shape axis, offering rusqlite or sqlx as the two candidates. Phase
10b found both refuted under the port as it stood, each by its own mechanism:
rusqlite’s Transaction<'_> is !Send, so a live handle costs the
SendProjectionStore impl; sqlx’s transaction could not be produced by a
total synchronous begin at all. That result went to PS-2’s owner, and the
owner’s answer is ADR-0062: the sqlx refutation was a defect in the port’s
signatures, not a property of the axis, and the signatures moved. The
rusqlite refutation stands — it is a property of that driver — which is
why the far end is a sqlx store and lives in this crate.
§The invariant
A read-model write and its checkpoint write must be one transaction, or a
restart either replays applied events or skips unapplied ones.
commit replays the caller’s
statements and does the checkpoint upsert on the same [Transaction], then
commits once.
§Schema
migrations/0002_projection_checkpoint.sql, applied by
apply_projection. Read-model tables
are the application’s business; this adapter owns the checkpoint and the
transaction that carries it.
Structs§
- Postgres
Projection Batch - A Postgres projection batch: an owned list of statements that has been sent to the server exactly never.
- Postgres
Projection Store - A Postgres-backed projection store.
Enums§
- PgParam
- One bound parameter, owned.
Constants§
- PROBE_
TABLE conformance - The conformance suite’s own read model.