happenstance-sqlite 0.8.0

SQLite event store and projection store adapters for happenstance.
Documentation
# happenstance-sqlite

The SQLite event store and projection store adapters for
[happenstance](https://github.com/Wet-Ink-Corporation/happenstance) — a
storage-agnostic event sourcing library built on the
[Dynamic Consistency Boundary specification](https://dcb.events/specification/).

New to happenstance? [The happenstance guide](https://wet-ink-corporation.github.io/happenstance/)
explains event sourcing and dynamic consistency boundaries from the beginning,
with programs you can run.

[![Buy me a coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-support-yellow?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/ryanbritton)

> **Status: conformant, and in the `0.8.0` release set.** This is the first
> happenstance adapter to pass
> [`happenstance-testkit`](https://crates.io/crates/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`](https://crates.io/crates/happenstance),
  and reach for this crate only to choose where the events live.
- **Want the contract without a driver?**
  [`happenstance-core`](https://crates.io/crates/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`](https://crates.io/crates/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

```toml
happenstance-sqlite = "0.8"                                # the event store
happenstance-sqlite = { version = "0.8", features = ["projection-store"] }
happenstance-sqlite = { version = "0.8", features = ["sync"] }   # + the ingest port

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

```toml
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.

**`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`. It also
implements `SendWriteGroupStore`, which reads the log back in the writes that
made it (#420), so it can be the local side of `happenstance-sync`'s runner,
`runner::Edge` (#244), against any `SyncPeer`. This crate ships no peer of its
own and no network transport, and SY-7, SY-10 and SY-29, which the port carries, are
still `[PROVISIONAL]`.

**Schema version 2.** `open`, `open_on` and `open_in_memory` apply migration 2
to a file that lacks it: two columns on `event` recording which rows one write
put in, and the marker raised to 2. `new`, which wraps a connection without
migrating it, refuses a file still at 1 with `SchemaNeedsMigration`; open it
once through `open_on` first. A build older than this one refuses a file this
one has opened, so upgrade every process that opens a store before any of them
opens it. Rows written before the migration read back as groups of one.

**Schema version 3.** The same three constructors apply migration 3 on open:
a table, `event_removed`, and an `AFTER DELETE` trigger on `event` that
records the origin identity of every row deleted from the file, by this crate
or by any other client (`sqlite3`, a retention script). Ingest skips an event
whose identity is recorded there and counts it in `Ingested::skipped`, so a
pruned replica that re-pulls, or is re-pushed, what it pruned neither takes the
events back nor refuses its own as `UnheldOwnIdentity` (SY-40, #483, #484).
`new` refuses a file still at 2 with `SchemaNeedsMigration`, and a build older
than this one refuses a file at 3, so upgrade every process that opens a store
before any of them opens it. Rows deleted before the migration are not
recorded; to record one by hand, run `INSERT INTO event_removed (origin_store,
origin_position) VALUES (X'<origin store id, 16 bytes>', <origin position>)`.
The record grows by one small row per removed event and is kept for ever:
deleting a row of it lets that identity be ingested again, so do that only once
no peer can offer the event. A restore from a copy of the file rolls the record
back with the log.

## 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.

```rust,ignore
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 |

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.

## What its conformance fixtures decline

A rule whose capability a fixture declines still runs, and reports the fixture's stated
reason as a `SKIP` line rather than vanishing from the binary (CF-18). A default
`cargo test` does not show that line; `--show-output` does. So the declines are listed
here, where a reader choosing this adapter will see them. Every capability the table does
not name is supported.

| Fixture | Capability | Why it is declined |
| --- | --- | --- |
| `SqliteFixture` | `MID_BATCH_FAULT` | By scope, not by incapacity. The injection exists, an `AFTER INSERT` trigger exercised by `tests/append.rs`, and is not armed from the fixture, so that ES-35's fault falsifier is not retired as a side effect. Atomicity under a fault is still checked by that test |
| `SqliteFixture` | `READ_FAULT` | By incapacity. A read is one `rusqlite` statement held open over a local file, so there is no fetch between two pages to fail |
| `SqliteFixture` | `HELD_ABOVE_FRONTIER` | By the testkit's default, which is true here: a row is visible from the moment it commits, so nothing is ever held above a frontier |

The projection fixture, `SqliteProjectionFixture`, declines nothing. The reasons in full are
on the constants in `tests/support/mod.rs`.

## 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](https://github.com/Wet-Ink-Corporation/happenstance/blob/main/.kb/decisions/0029-msrv-raised-to-1-97-1.md)).
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](https://github.com/Wet-Ink-Corporation/happenstance/blob/main/.kb/decisions/0067-msrv-after-1-0-rises-are-bounded.md)).

Before `1.0.0`, a rise ships in a `0.x` minor, which a `"0.x"` requirement never
resolves across
([ADR-0037](https://github.com/Wet-Ink-Corporation/happenstance/blob/main/.kb/decisions/0037-msrv-becomes-a-promise-at-0-2-0.md)).
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.