Documentation

Exception thrown when a persisted event cannot be decoded.

Items in the write-behind queue: either an event to insert or a flush marker that the writer thread signals after processing all preceding items.

Events are queued unencoded and CBOR-encoded on the writer thread: the encoding of an event carrying a large payload otherwise sits on the caller's thread. The bounded queue briefly pins event values instead of compact bytes, but the writer drains whole-queue batches so the window is short.

Bracket-style wrapper around mkSQLiteEventStore. Creates the database, schema, and writer thread, runs the callback, then flushes queued writes and cancels the writer thread on exit. The writer thread is linked so that crashes surface immediately in the calling thread.

If a legacy state file exists at legacyStateFile, events are migrated into SQLite automatically before the callback runs.

Create an EventStore backed by a SQLite database at the given file path. The database and schema are created on first use if they do not exist. Returns (conn, store, flush, reinitLastSeen, cleanup). Internal — prefer withSQLiteEventStore which handles cleanup, migration, and flushing automatically.

Background writer that drains the queue and batch-inserts into SQLite. Each iteration blocks for at least one item, then flushes everything available. Events are CBOR-encoded here, off the caller's thread, then batch-inserted in a single transaction, and any flush markers in the batch are signalled. Encode errors surface as writer thread crashes, which are linked to the caller.

Block until all items currently in the write queue have been flushed to SQLite. Sends a flush marker through the queue and waits for the writer thread to signal completion.

Migrate events from a legacy newline-delimited JSON file into SQLite. Writes directly to the database, bypassing the async write queue (migration runs at startup before inputs are processed). After inserting, calls reinitLastSeen to sync the in-memory event id TVar with the database.

Safe to call when the legacy file does not exist (no-op). Not safe to re-run: duplicate event ids will cause a primary key constraint violation.

On success the legacy file is renamed to path.migrated so that subsequent restarts skip the migration step automatically.

Current schema version. Bump this and add a migration step to migrateStep whenever the schema changes.

Re-encode a single event row given its event id and stored bytes, used by the version 1 (JSON) to version 2 (CBOR) migration. Must throw when the row cannot be decoded.

Initialise connection pragmas, then create or migrate the schema to nextVersion using SQLite's built-in user_version pragma.

Read the schema version from PRAGMA user_version (0 for a fresh DB).

Apply all pending migrations from version v up to nextVersion. Each step runs together with its version bump in one transaction (PRAGMA user_version is transactional), so a crash or decoding failure mid-migration rolls back to a well-defined version.

Individual migration steps. Pattern-match on the source version.

Re-encode all event rows using the given ReencodeRow function (the version 1 JSON to version 2 CBOR migration). Rows are processed in batches of ascending event id so memory stays bounded for large databases. Runs inside the caller's transaction.

Archive the current database before rotation removes the events, into an old-state subdirectory next to the database, with the log id inserted before the extension (e.g. old-state/state-42.db). Uses VACUUM INTO so the snapshot reflects all committed (WAL) data in a single self-contained file, regardless of WAL checkpoint state. The destination is removed first if present (e.g. a re-rotation at the same log id), since VACUUM INTO requires it not to exist.