Skip to main content

Crate happenstance_sqlite

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 the Send flavour, for two independent reasons that each fire on their own. See projection_store for 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 still error[E0195]. ADR-0017 removed the lifetime, so type Batch = SqliteBatch; and commit(&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§

connectionevent-store or projection-store
The one connection configuration both stores in this crate use.
event_storeevent-store
SQLite-backed SendEventStore.
projection_storeprojection-store
SQLite-backed SendProjectionStore.