Module event_store
event-store only.Expand description
SQLite-backed SendEventStore.
§Status: every event-store path is real
Migration 1, the persisted identity, the connection settings, append,
read, head and contains_event_id all have real bodies, and four test
targets read them back out of SQLite — tests/migration.rs,
tests/append.rs, tests/read.rs and tests/wide_query.rs. The types
were never stubbed: the connection is a real [rusqlite::Connection], the
error enum wraps [rusqlite::Error], and SqliteReadStream is the state
machine the real read path uses. A skeleton that stubs its associated types
has stubbed the only part of it a type checker can disagree with.
§Why the stream is a hand-written state machine
rusqlite is synchronous. The only correct way to call it from an async
context is [tokio::task::spawn_blocking], and spawn_blocking panics
when there is no runtime in thread-local scope. Meanwhile
EventStore::read is deliberately
not async — it returns the stream at the top level so that the Send
flavour can mark the stream Send rather than merely the future that
produces it (ADR-0001, ADR-0008).
Put those together and the consequence is forced: read runs on whatever
thread called it, possibly outside any runtime, so it must not spawn. The
spawn has to be deferred to the first poll_next, which by definition runs
under an executor. Laziness stops being a nicety and becomes load-bearing
— it is what makes the two constraints compatible at all.
One residual risk survives that, and it is why
SqliteEventStoreError::NoRuntime exists: a poll under a non-tokio
executor (futures::executor::block_on, say) is still runtime-less.
[tokio::runtime::Handle::try_current] turns that from a panic into an
ordinary stream error, which is what a lazy stream’s contract already
promises — failures surface as Err items rather than up front.
§Intended schema
Migrations 1 and 2, exactly as SqliteEventStore::open applies them on
every connect — through a private migrate, which is why this block and not a
rustdoc link is what a reader has. It is compared object-by-object against
sqlite_master by
tests/migration.rs::module_doc_schema_matches_sqlite_master, because a
reviewer reading SQL prose against SQL code is the check that passes by
fatigue.
CREATE TABLE event (
position INTEGER PRIMARY KEY AUTOINCREMENT, -- monotonic, gaps allowed
event_type TEXT NOT NULL,
data BLOB NOT NULL,
metadata BLOB, -- nullable on purpose
tags BLOB NOT NULL, -- canonical sorted encoding
origin_store BLOB,
origin_position INTEGER,
recorded_at INTEGER NOT NULL,
UNIQUE (origin_store, origin_position)
);
CREATE INDEX event_type_idx ON event(event_type, position);
CREATE TABLE event_tag (
tag TEXT NOT NULL,
position INTEGER NOT NULL REFERENCES event(position),
event_type TEXT NOT NULL, -- covering column, deliberately not in the key
PRIMARY KEY (tag, position)
) WITHOUT ROWID;
CREATE TABLE tag_cardinality (
tag TEXT PRIMARY KEY,
events INTEGER NOT NULL
) WITHOUT ROWID;
CREATE TABLE store_meta (
k TEXT PRIMARY KEY,
v BLOB NOT NULL
) WITHOUT ROWID;
-- Migration 2 (#420), once, on a file whose marker reads 1.
ALTER TABLE event ADD COLUMN write_group INTEGER; -- first position of the write
ALTER TABLE event ADD COLUMN group_guard BLOB; -- on that first row onlyEvery line of it is load-bearing, and the two amendments in the middle are the reason this block was rewritten rather than merely filled in:
-
event_typeonevent_tagis a covering column and not part of the key. In the key it would break the position ordering that makes a tag’s range already sorted; absent — which is what this block published while the bodies weretodo!()— it forces a query item constraining both type and tags into a join back toevent, walked while theBEGIN IMMEDIATEwrite lock is held, with every other writer queued behind it. That is a conformant adapter that serialises every writer, and it passes every rule (ADR-0022 §7). -
tag_cardinalityis a requirement rather than a convenience. Multi-tag items must be probed most-selective-tag-first and SQLite cannot supply per-value cardinality:ANALYZEstores an average, which is exactly wrong for a tag set where one value matches a third of the log and another matches one percent.That requirement is only true because the intersection chain is correlated —
query_sql.rs’s module documentation is the long form, and it is a private module, so this is a path rather than a link. On the uncorrelated shape this crate emitted until then, obeying it cost 37x–42x rather than earning anything, because the chained arm was materialised and the seed’s selectivity could not reach it. A future edit that returns the chain toposition IN (…)must delete this bullet in the same change, or the crate will be requiring the slower ordering in its own public documentation. Measured inexperiments/correlated-exists-guard/.
And three that predate them:
AUTOINCREMENTis deliberate. It guarantees positions are never reused after a delete, which plainrowiddoes not, and the specification requires uniqueness across the store’s whole lifetime. It also permits gaps, which is why nothing here and no rule may assume+ 1.metadatais nullable.NoneandSome(<empty>)are two values the contract keeps apart, and a store that folds them has lost one.- The
EventIdorigin pair isUNIQUEtogether, not separately: one constraint serving two jobs, the indexcontains_event_idprobes and the guard that stops ingest storing one event twice.
store_meta carries this store’s own StoreId, minted once at schema
creation and read back on every open, beside the schema-version marker that
gives migration 2 something to test against. See
SqliteEventStore::remint_identity for what that mint-once choice costs.
Migration 2 records write groups (SY-39): every row one append or one
ingested group wrote carries the position of the write’s first row in
write_group, and that first row carries an ingested group’s guard in
group_guard. It raises the marker to 2, so a build that predates it
refuses the file rather than relay its groups torn. A row written before it
has NULL in both and reads back as a group of its own; there is no
backfill, because nothing recorded which rows one call wrote.
§Cancellation
What a dropped append future does here: nothing, because there is nothing
to drop. append refuses an empty batch, checks this store’s declared
ceilings, locks the connection and calls append_locked inline. There is no
.await anywhere in that body — none anywhere in this module at all — so
a future polled once has already run to completion by the time poll returns,
and no outcome depends on whether the caller then drops it. A dropped
append future cannot be cancelled by this adapter.
This is the statement ES-23 obliges every adapter to make. The clause is
[FROZEN], its two outcomes are the append committed and it did not, and
the port refuses to choose between them on a caller’s behalf
(EventStore::append’s own
# Cancellation section) precisely so that each adapter has to answer.
It does not license the opposite reading either. A caller MUST NOT treat a dropped future as evidence about any store, this one included: generic code binds the port rather than this crate, and the next store in the same program may answer differently. Where an outcome genuinely has to be resolved, ES-24 is the mechanism — a conditional append is at-most-once under verbatim reissue, so reissuing the identical batch settles it with no identity and no idempotency key.
The answer survives the move this crate is most likely to make. ADR-0012
and the port’s own documentation both name a pooled rusqlite adapter working
in tokio::task::spawn_blocking as “the shape that looks cancellation-safe
and is not” — dropping the JoinHandle does not cancel the closure, so the
COMMIT still runs. That is the same answer as the one above reached by a
different route: moving the work would change where it happens, not whether
a drop can stop it. What such a change would owe this section is the new
reason, not a new verdict.
It is checked rather than promised. tests/cancellation_statement.rs fails if
this section goes missing, and fails again if append acquires a suspension
point and the section stops being true — the half ADR-0012 recorded that a
heading-check alone could not have.
Structs§
- Sqlite
Event Store - A SQLite-backed event store.
- Sqlite
Read Stream - The stream
SqliteEventStore::readreturns.
Enums§
- Sqlite
Event Store Error - How
SqliteEventStorefails.
Constants§
- SCHEMA_
VERSION - The migration this build knows how to operate.