happenstance-sqlite
The SQLite event store and projection store adapters for happenstance — a storage-agnostic event sourcing library built on the Dynamic Consistency Boundary specification.
New to happenstance? The happenstance guide explains event sourcing and dynamic consistency boundaries from the beginning, with programs you can run.
Status: conformant, and in the
0.4.5release set. This is the first happenstance adapter to passhappenstance-testkit's conformance suite against a real file on disk — the event store family, the concurrency family, the generated model family and the projection family. Thepublish = falsethis callout used to name is gone. It is host only: it does not build forwasm32-unknown-unknown—rusqlitefails atlibsqlite3_sys, and reads hop throughspawn_blocking— and nothing in the gate checks that target.references/seeds/sqlite-on-wasm.mdhas the detail.
Which crate do I want?
- Writing an application? Use
happenstance, and reach for this crate only to choose where the events live. - Want the contract without a driver?
happenstance-coreis the smaller semver surface, and it ships an in-memory reference store. - Writing your own adapter? Read this one as a worked example, then measure
it against
happenstance-testkit. A crate that compiles is not an adapter until it has run that suite.
Features, and the one that costs you a promise
= "0.4" # the event store
= { = "0.4", = ["projection-store"] }
= { = "0.4", = ["sync"] } # + the ingest port
= "0.40" # only for tables of your own
You do not need that third line to name the driver. Connection,
rusqlite::Error and rusqlite::types::Value are all on this crate's public
signatures, so all three are re-exported: reach them as
happenstance_sqlite::rusqlite::…. What that buys is type identity — the
rusqlite::Error you match on is the one this crate's error enum actually
carries, rather than a second copy that prints the same and meets you as
error[E0308] the first time you try to act on a failure. Add a rusqlite
line of your own when you use SQLite for tables of your own; the re-export is
not a substitute for a dependency, and it forwards only the features this crate
enabled.
tokio is not re-exported, and it is the one place you may need a line we do
not give you. tokio::task::JoinError and tokio::runtime::TryCurrentError
are variants of the error enums, so matching on either means naming tokio
yourself:
= "1" # only to match on JoinError
It was re-exported and is not any more. This crate takes tokio at
features = ["rt"], so happenstance_sqlite::tokio was a partial tokio —
no macros, no rt-multi-thread, no time — and reaching for it and then
writing #[tokio::main] produced an error[E0433] further from its cause than
the mismatch the re-export was there to prevent. Your own line resolves to the
same tokio this crate uses for any semver-compatible requirement, which is
every consumer who already had one.
event-store is on by default. projection-store is not, and the asymmetry
is deliberate.
The event store implements a port whose clauses are frozen. The projection store
implemented one that was not, until ADR-0063: ProjectionStore was provisional
while PS-2's bar for freezing it — a hostile store failing the suite, and two
adapters at opposite ends of the batch-shape axis passing it — was met on its
first half only. The second half was met by ADR-0062 and the port is frozen
now, so projection-store forwards nothing to the contract crate any more and
the surface it gates makes the same semver promise the event store does. It
stays off by default because a consumer who wants only the event store should
not compile the other role.
That is worth choosing rather than inheriting. Nothing about the event store changes either way, and a projection built on this today is built on a frozen port: the next edit it needs will come with a decision record and a major.
sync is off by default, and it is the store's half of replication. It
implements happenstance-sync's SendIngestStore for SqliteEventStore, so
generic code bound on IngestStore accepts it, and re-exports the port as
happenstance_sqlite::happenstance_sync. It turns on event-store, and
happenstance-core's serde feature through happenstance-sync. What it does
not give you yet is replication: there is no runner (issue #244) and no network
peer, and several of the SY clauses the port carries are still
[PROVISIONAL].
The shape it represents
Serialising, Send, native. One rusqlite::Connection behind one Mutex,
with no pool: writers queue by construction and positions are assigned under a
lock. rusqlite is synchronous, and what this crate does about that differs by
path — the two halves are worth separating, because one of them is the reason a
dropped append here is safe.
The read path defers a spawn_blocking until the stream's first poll, which
is what lets read return the stream at the top level rather than from inside a
future. The projection store runs its work on a blocking task too, through
in_blocking_task.
append, head and contains_event_id do neither. They run inline under the
connection mutex, on whatever thread polls them — there is no .await anywhere in
the event store's module, which its own # Cancellation section states and a
source-scanning test (tests/cancellation_statement.rs) enforces on every build.
That absence is not an oversight: it is exactly what lets this adapter discharge
[FROZEN] ES-23 by saying a dropped append future commits nothing, because a
future with no suspension point has already run to completion when poll returns.
It is deliberately one point in a portfolio rather than the reference. A port frozen against this shape alone would be frozen against SQLite wearing four hats, which is why the workspace keeps instruments at the other end of the same axis — a store that assigns positions outside the transaction, and one with no interactive transaction at all.
use SqliteEventStore;
let store = open?;
Durability, as configured rather than as hoped
Every connection this crate opens runs under the same three settings, and each is a public constant you can assert against rather than a paragraph you have to trust:
| Setting | Value | Why |
|---|---|---|
journal_mode |
WAL |
readers do not block the writer, which is what makes a long replay and a second handle onto one file workable at the same time |
synchronous |
NORMAL (1) |
durable across a process crash; on power loss it can lose the tail since the last checkpoint. OFF is not on the menu — the specification names it as the wrong implementation the reopen rule exists to reject |
busy_timeout |
15,000 ms |
finite and generous, and both halves are load-bearing. Raised from 5,000 on measurement: at the old value the concurrency target went red on a SQLITE_BUSY in 7 launches of 8 under maximum contention, and at the new one in 0 of 16. It costs nothing when nothing is contended — the handler returns as soon as the lock is acquired — so the cap bounds only the tail. It stays finite because an unbounded handler would turn a livelock into a hung job naming no rule. An append whose BEGIN IMMEDIATE outlasts it is refused as AppendError::Busy: nothing was written, and deciding again is safe |
A caller that must keep its own settings, for example a file kept in
journal_mode = TRUNCATE where WAL's shared-memory file cannot live, opens the
connection itself and hands it to SqliteEventStore::open_on, and re-mints with
SqliteEventStore::remint_identity_on. Neither sets a pragma, so this table then
describes nothing: the durability and contention trade-offs are the caller's.
Limits this store enforces
append refuses anything above these as AppendError::ExceedsStoreLimit — never
by truncating, and never as a generic store error:
| Limit | Value |
|---|---|
bytes of data on one event |
1,048,576 |
| tags on one event | 128 |
| events in one append | 256 |
Every one of them is well above the floor the specification requires of any store, and every one is checked from both sides: the suite appends exactly the limit and requires it to be accepted, then one more and requires it to be refused.
Positions may have gaps. The table is AUTOINCREMENT, so a position is never
reused after a delete, and nothing you write against this store may assume the
next one is + 1.
Minimum supported Rust version
Rust 1.97.1, the rust-version this crate declares
(ADR-0029).
After 1.0.0 the floor rises only in a minor release, never a patch; only to a
Rust stable at least six months old on the day that minor ships; and always with
a CHANGELOG.md entry naming the old floor, the new one and what forced it
(ADR-0067).
Before 1.0.0, a rise ships in a 0.x minor, which a "0.x" requirement never
resolves across
(ADR-0037).
From 1.0.0, what keeps a rise from reaching you is your workspace's resolver,
not this crate's: under resolver = "3", the default for an edition-2024 root,
or with resolver.incompatible-rust-versions = "fallback" set, Cargo prefers
the newest version whose rust-version your lowest package.rust-version (or
your rustc, if you declare none) satisfies, and cargo update says so by
printing to latest Rust 1.xx compatible versions where resolver 2 prints to
latest compatible versions. On resolver 2, only your lockfile holds you back.
Licence
MIT OR Apache-2.0.