Module projection_store
projection-store only.Expand description
SQLite-backed SendProjectionStore.
§Stability: covered by the crate’s version, behind a feature
This module was exempt from semver while the projection port beneath it was
unfrozen. It is not any more: ADR-0063 froze ProjectionStore for 0.3.0,
and everything here is semver-binding like the rest of happenstance-sqlite.
It still sits behind the off-by-default projection-store feature, which has
forwarded nothing to happenstance-core since 0.3.0 (ADR-0063), and that
crate’s unstable-projection was removed in 0.4.0. It only keeps the
second role out of a build that wants the event store alone.
On docs.rs the feature shows as a badge on this module. The badge says which flag; this paragraph says that the flag no longer carries a semver exemption, because a reader cannot tell that from a feature name.
§Status: a projection store that has run the suite it did not write
SQLite is the adapter that makes the checkpoint invariant easy to honour: the
read-model writes and the checkpoint update share one transaction, so there is
no window in which they can disagree. tests/projection.rs is where that
stops being a claim — it mounts
happenstance_testkit::projection_store_conformance! against a real temporary
file, and every rule in the family either runs against this store or is
reported as a skip carrying the fixture’s own stated reason.
A green run here does not, on its own, buy PS-2. That clause wants the suite
green at both ends of the batch-shape axis, and this is a replay-at-commit
shape like MemoryProjectionStore. The other end is happenstance-postgres’s
LivePostgresProjectionStore, whose batch is a live transaction; see
SqliteBatch for why no rusqlite adapter can supply it.
§Why the batch is a buffer and not a rusqlite::Transaction
The port’s documentation used to say a batch is a live transaction, and
justified the lifetime on type Batch<'a> with “a transaction cannot outlive
its connection”. ADR-0017 removed the lifetime and PS-4 now says the reverse
— a Batch MUST NOT be required to be a live transaction — with this crate
as one of the reasons why. Even while the lifetime existed,
type Batch<'a> = rusqlite::Transaction<'a> failed on
SendProjectionStore for two independent reasons, each confirmed against
this crate:
- [
rusqlite::Connection] isSendand notSync— it holds aRefCell<InnerConnection>— so a store that owns one directly is notSync, so&Selfis notSend, so every future in the trait is rejected, includingcheckpoint, which never touches a batch at all. rusqlite::Transaction<'_>is itself!Send, socommitandrollbackare rejected on the batch parameter alone even when the store is wrapped to beSync.
Reason 1 is fixed here by Mutex; reason 2 cannot be fixed at all without
giving up the live handle. So the batch is an owned, Send, replayable write
set — SqliteBatch — opened into a real transaction inside commit. That
satisfies the port’s obligation (read model and checkpoint move together),
and it is now the shape the port asks for rather than a departure from it.
§The schema this store owns
CREATE TABLE projection_checkpoint (
projection_id TEXT NOT NULL PRIMARY KEY,
position INTEGER NOT NULL,
authority TEXT NOT NULL
) WITHOUT ROWID;
CREATE TABLE projection_meta (
k TEXT NOT NULL PRIMARY KEY,
v INTEGER NOT NULL
) WITHOUT ROWID;
CREATE TABLE projection_protection (
projection_id TEXT NOT NULL PRIMARY KEY
) WITHOUT ROWID;projection_protection holds one row per projection protected from
reset (PS-18), written through
SqliteProjectionStore::protect_from_reset. It is a mark the domain sets,
not a policy this adapter holds, and SCHEMA_VERSION says why a file that
carries one is marked differently from a file that does not.
The authority column is the half an earlier sketch of this schema left out,
and leaving it out is not a shortcut but an impossibility: without it
Checkpoint::Rebuilding has
nowhere to come from, so a reader asking whether the rows in front of it are
authoritative is told Live over a half-built read model by every
implementation. The absence of a row is
NeverRun — never a sentinel row
at position zero, which would make “never run” and “committed at the first
position” the same state and skip event 1 permanently and silently.
Read-model tables themselves are the application’s business; this adapter owns
only the checkpoint and the transaction that carries it. That is also why
reset applies the caller’s
deletes: an adapter that truncated a table of its own choosing would be
inventing a read model it does not own.
Under feature = "conformance" one more table appears —
projection_probe(k, v), the conformance suite’s own read model, written
through ProjectionProbe. It is behind
that feature and not behind a runtime flag, so it cannot reach an
application’s database.
§Two version markers in one file, on purpose
An event store and a projection store on one path are two connections, and
either may be opened without the other — they are separate crate features. So
this schema carries SCHEMA_VERSION in its own projection_meta table
rather than sharing the event store’s store_meta counter: the two schemas
advance on different stories’ schedules, and one counter would make either
migration a breaking change to the other.
§One crate, one runtime seam
Every method that reaches SQLite hops onto a blocking thread through the
runtime it is executing on ([Handle::try_current]), falling back to the
[tokio::runtime::Handle] captured at construction and reporting
NoRuntime when there is neither.
That is ADR-0022 §9’s decision for the event store’s read path, applied here
unchanged: a second, different answer inside one crate is the defect. It is
also what keeps the MutexGuard and the await
apart — a guard held across an await would make the future !Send and cost
this adapter its SendProjectionStore impl.
Structs§
- Pending
Statement - One buffered statement and its bound parameters.
- Sqlite
Batch - An in-flight write against a
SqliteProjectionStore. - Sqlite
Projection Store - A SQLite-backed projection store.
Enums§
Constants§
- SCHEMA_
VERSION - The highest projection schema version this build knows how to operate.