happenstance-sqlite 0.4.1

SQLite event store and projection store adapters for happenstance.
Documentation

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.

Buy me a coffee

Status: conformant, and in the 0.4.1 release set. This is the first happenstance adapter to pass happenstance-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. The publish = false this callout used to name is gone. It is host only: it does not build for wasm32-unknown-unknown — rusqlite fails at libsqlite3_sys, and reads hop through spawn_blocking — and nothing in the gate checks that target. references/seeds/sqlite-on-wasm.md has 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-core is 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

happenstance-sqlite = "0.4"                                # the event store
happenstance-sqlite = { version = "0.4", features = ["projection-store"] }

rusqlite = "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:

tokio = "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 happenstance_sqlite::event_store::SqliteEventStore;

let store = SqliteEventStore::open("events.db")?;

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

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.