Skip to main content

Module projection_store

Module projection_store 

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

  1. [rusqlite::Connection] is Send and not Sync — it holds a RefCell<InnerConnection> — so a store that owns one directly is not Sync, so &Self is not Send, so every future in the trait is rejected, including checkpoint, which never touches a batch at all.
  2. rusqlite::Transaction<'_> is itself !Send, so commit and rollback are rejected on the batch parameter alone even when the store is wrapped to be Sync.

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§

PendingStatement
One buffered statement and its bound parameters.
SqliteBatch
An in-flight write against a SqliteProjectionStore.
SqliteProjectionStore
A SQLite-backed projection store.

Enums§

SqliteProjectionStoreError
How SqliteProjectionStore fails.

Constants§

SCHEMA_VERSION
The highest projection schema version this build knows how to operate.