Crate happenstance_sqlite
Expand description
SQLite adapters for happenstance: an event store and a projection store.
§Status: an adapter, and it has run the suite
Every operation that touches SQL has a real body — migration, append,
read, head,
contains_event_id, checkpoint and commit — and each of them is executed
against a real file on disk rather than against something standing in for
one. happenstance-testkit’s
conformance suite is mounted three times: tests/conformance.rs carries the
event-store family and the model family, tests/projection.rs the
projection-store family, and tests/concurrency.rs the concurrency family.
Passing that suite is what makes an adapter in this workspace rather than an
instrument, and it is the bar this crate has now cleared.
Whether the crate is published is a different question with a different
owner. publish = false is gone from its manifest, and its absence is half
of an atomic pair: PUBLISHABLE (xtask/src/package.rs) names this crate,
and reconcile fails on either half alone. So this crate is packaged by the
gate, and it has been on crates.io since 0.2.0. Passing the suite and being
live on a registry are still two claims, and they have separate records: the
suite’s is above, and the registry’s is CHANGELOG.md, one entry per release.
§The shape this crate represents
Serialising, Send, native — and native means host only. One connection
behind one Mutex, so writers queue by construction and
positions are assigned under a lock. It implements SendEventStore
and SendProjectionStore, and a port
frozen against this shape alone would be frozen against SQLite wearing four
hats. It does not build for wasm32-unknown-unknown: rusqlite fails at
libsqlite3_sys, reads hop through spawn_blocking, and no gate step checks it.
§What the type checker has already decided
Two results, both compiled rather than reasoned:
- A
rusqlite::Transaction<'a>batch is not available on theSendflavour, for two independent reasons that each fire on their own. Seeprojection_storefor both, and for the owned batch that replaces it. - While the port declared a generic associated type, binding an owned type
to it did not free an implementer from spelling the parameter
Self::Batch<'_>literally; writing the concrete type was stillerror[E0195]. ADR-0017 removed the lifetime, sotype Batch = SqliteBatch;andcommit(&self, batch: Self::Batch, …)now compile — this crate is one of the impls that shows it.
§What is settled, and what is still open
The driver is rusqlite, chosen for the synchronous, bundled,
local-first shape it gives — and it is rusqlite without a pool, because
one Mutex-guarded connection is the serialising instrument the portfolio
needs. sqlx is not discarded; it is where happenstance-postgres sits, at
the other end of that axis.
The append-condition strategy and tag storage were the two decisions
this page listed as open, and ADR-0022 settled both against measurement
rather than preference. A guard is one SELECT max(position) over the
guard’s derived query inside a transaction opened BEGIN IMMEDIATE; tags
live in event_tag(tag, position), WITHOUT ROWID, with event_type
carried as a covering column and a tag_cardinality table supplying the
per-value selectivity SQLite’s ANALYZE cannot. Tags
is still canonically sorted, and event_store carries the schema those
decisions produced with the measurements that chose it.
Two subjects the same ADR left open are recorded here rather than answered,
each with an open-question atom of its own in the repository’s knowledge
base: whether ES-17’s &[Event] marker on append can be lifted, which
wants a second adapter’s measurement this crate cannot supply alone
(es-17-two-adapter-measurement-is-unscheduled), and which document owns a
fixture-constant clause (cf-40-fixture-limits-ownership). Neither is a
property of this crate’s code, and neither is waiting on it.
What a dropped append future does is ES-23’s question, and it is
answered in event_store’s own # Cancellation section — beside the
body it is about.
§Not the Cloudflare adapter
A Durable Object’s SQLite is reached through the Workers SqlStorage API,
not through a SQLite driver, and its futures are !Send. That is a separate
adapter crate implementing
EventStore rather than
SendEventStore — not a feature of this
one.
Re-exports§
pub use rusqlite;pub use happenstance_core;pub use happenstance_sync;sync
Modules§
- connection
event-storeorprojection-store - The one connection configuration both stores in this crate use.
- event_
store event-store - SQLite-backed
SendEventStore. - projection_
store projection-store - SQLite-backed
SendProjectionStore.