Skip to main content

Module projection_store

Module projection_store 

Available on crate feature 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 plpgsql function raising with a custom ERRCODE is the textbook answer and gives a nicer SQLSTATE. It needs a dollar-quoted body in migrations/, which is exactly what crate::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 UPDATE takes the row lock the guard then reads under.

Structs§

NeonProjectionStore
A projection store over Neon’s serverless /sql HTTP endpoint.
NeonWriteBatch
An accumulated list of statements, owned outright.

Functions§

probe_tableconformance
The suite’s own read model, as SQL rendered for one configuration.