Skip to main content

Module event_store

Module event_store 

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

Every 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_type on event_tag is 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 were todo!() — it forces a query item constraining both type and tags into a join back to event, walked while the BEGIN IMMEDIATE write 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_cardinality is a requirement rather than a convenience. Multi-tag items must be probed most-selective-tag-first and SQLite cannot supply per-value cardinality: ANALYZE stores 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 to position IN (…) must delete this bullet in the same change, or the crate will be requiring the slower ordering in its own public documentation. Measured in experiments/correlated-exists-guard/.

And three that predate them:

  • AUTOINCREMENT is deliberate. It guarantees positions are never reused after a delete, which plain rowid does 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.
  • metadata is nullable. None and Some(<empty>) are two values the contract keeps apart, and a store that folds them has lost one.
  • The EventId origin pair is UNIQUE together, not separately: one constraint serving two jobs, the index contains_event_id probes 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§

SqliteEventStore
A SQLite-backed event store.
SqliteReadStream
The stream SqliteEventStore::read returns.

Enums§

SqliteEventStoreError
How SqliteEventStore fails.

Constants§

SCHEMA_VERSION
The migration this build knows how to operate.