Module projection_store
projection-store only.Expand description
The Neon-backed ProjectionStore, and the batch that is not a transaction.
§What this falsified, and what the port did about it
ProjectionStore’s Batch used to be a generic associated type,
type Batch<'a> where Self: 'a, because “a transaction cannot outlive the
connection that opened it”. Neon has no connection and no transaction, so the
lifetime had nothing to borrow from. This crate bound an owned type to the
GAT — type Batch<'a> = NeonWriteBatch; — and it compiled, because a GAT is
free to ignore its parameter. ADR-0017 has since removed the parameter, and
the binding below is plainly type Batch = NeonWriteBatch;.
That made this adapter the owned-batch evidence from the far end of the
transport axis, and it surfaced two places where the port asked for something
this adapter had no way to mean. Both have since been answered rather than
left standing. ProjectionStore::begin became synchronous and infallible
for this adapter’s sake — PS-6 — and then went back to async and fallible
under ADR-0062, because the synchronous shape forbade a batch that is a live
transaction and PS-6’s own falsifier had fired. What survives is PS-6’s
discipline, now on the implementer: begin here is a Vec::new() and a
stamp, a future ready at its first poll, and a unit test below proves it
makes no round trip by running it over a transport that fails every one.
ProjectionStore::rollback is async and fallible too, because Drop
cannot await and an adapter holding a real resource needs somewhere to release
it; this one holds none, so dropping the statement list is the whole of its
rollback.
§Where the atomicity actually comes from
The port’s invariant is that the read-model write and the checkpoint write
land together. This adapter gets that not from a transaction handle but from
the non-interactive batch: commit appends the checkpoint UPSERT to the
accumulated statements and sends all of them as one array in one round trip,
which the endpoint runs server-side inside one BEGIN/COMMIT. The invariant
is honoured. What is lost is the ability to decide anything between two
statements of the batch — which the projection port, unlike the event store
port, never asks for.
§Except in exactly one place, and this is how that is paid for
PS-16’s checkpoint regression is a decision: refuse, and leave the read model as it was. A guarded upsert reports a refusal as zero rows, and zero rows do not abort anything — so the caller’s statements, already earlier in the same batch, would commit with no checkpoint recording them. That is a partial application, which is precisely what PS-1 forbids.
happenstance-postgres answers it by re-reading inside the transaction and
then dropping the transaction. There is no transaction here to drop, and no
second look to take: the batch is decided before it is sent.
So the refusal is made to fail, in one more statement of the same batch,
and the failure carries its own evidence. After the guarded upsert, a
statement reads the checkpoint back and casts a marker string to bigint
when — and only when — the recorded position is not the one that was
attempted. The cast raises SQLSTATE 22P02 with the message invalid input syntax for type bigint: "hs-regression:<current>:<attempted>", which aborts
the whole batch — read-model statements included — and reconstructs
CommitError::CheckpointRegression with both positions and no second
round trip.
Two alternatives lost, and both are worth naming because the one chosen looks like a hack and is the only one that is not:
- A
plpgsqlfunction raising with a customERRCODEis the textbook answer and gives a nicer SQLSTATE. It needs a dollar-quoted body inmigrations/, which is exactly whatcrate::migration’s deliberately small splitter cannot see the end of — so it would buy a tidier error by putting a SQL parser in the migration path. - Read the checkpoint first, then commit is two round trips and a
time-of-check race: another runner may advance the checkpoint between the
read and the batch, and the batch would then commit a regression it had
already checked. The single-batch form has no window at all, because the
upsert’s
ON CONFLICT DO UPDATEtakes the row lock the guard then reads under.
Structs§
- Neon
Projection Store - A projection store over Neon’s serverless
/sqlHTTP endpoint. - Neon
Write Batch - An accumulated list of statements, owned outright.
Functions§
- probe_
table conformance - The suite’s own read model, as SQL rendered for one configuration.