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.
Status: conformant, and in the
0.3.0release 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: the crate-set re-plan put it in the release besidehappenstance,happenstance-coreandhappenstance-testkit. Only the registry can say whether that release has happened yet.
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.3" # the event store
= { = "0.3", = ["projection-store"] }
= "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.
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 |
5,000 ms |
finite and generous. Measured to absorb 64-way write contention with no SQLITE_BUSY; an unbounded handler would turn a livelock into a hung job that names no rule |
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.
Licence
MIT OR Apache-2.0.