Skip to main content

Crate agent_effects_sqlite

Crate agent_effects_sqlite 

Source
Expand description

SQLite store for agent-effects.

For CLI agents, desktop apps and single-node services. Several processes may share one database file.

let store = agent_effects_sqlite::SqliteStore::open("effects.db").await?;

§Durability and concurrency

SqliteStore::open configures:

  • WAL journal, so readers do not block the writer.
  • synchronous = FULL: a commit is on disk before it returns. The runtime persists an attempt before calling the remote system. Losing that write in a power cut would leave a Pending record for an effect that may have run, and the next call would run it again. NORMAL would allow exactly that.
  • busy_timeout of 5 seconds, so concurrent writers wait instead of failing.

Every change runs as “load, apply the pure EffectRecord operation, save” inside a BEGIN IMMEDIATE transaction. That takes the write lock up front, so two writers, even in different processes, cannot both read a record and then both write it. The record update also checks the version it read, as a second guard.

SQLite admits one writer at a time, and its busy handler is not fair: under contention a waiting writer can lose the race for the lock again and again until its busy timeout runs out. So writers in one process (every clone of one store) queue for their turn, first come, first served, before asking SQLite for the lock; only writers in other processes meet the busy timeout. Every commit is an fsync, so write throughput is bounded by the disk: tens of commits per second on some encrypted or copy-on-write filesystems, thousands on a fast SSD.

Times are stored as Unix milliseconds; sub-millisecond precision is dropped, as the EffectStore contract allows.

Structs§

SqliteStore
An EffectStore in a SQLite database.