Skip to main content

Module projection_store

Module projection_store 

Available on crate feature 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:

  • begin was total, synchronous and infallible. There was no Result, no await, and no argument to fail on.
  • sqlx’s only constructor for a transaction is Transaction::begin, which is async and fallible; Transaction’s fields are private, so the type cannot be assembled by hand. Pool::try_acquire is synchronous but yields a PoolConnection, and BEGIN is still a round trip.
  • ProjectionProbe::probe_write was 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§

PostgresProjectionBatch
A Postgres projection batch: an owned list of statements that has been sent to the server exactly never.
PostgresProjectionStore
A Postgres-backed projection store.

Enums§

PgParam
One bound parameter, owned.

Constants§

PROBE_TABLEconformance
The conformance suite’s own read model.