4.1 Connections

3 min read

Each hive holds a small, fixed set of SQLite connections, and which one an operation runs on decides both its isolation and what it can block on.

Connection	Count	Used for
Write	One per hive	Every mutating operation, and every read inside a bound read-write transaction.
Read pool	`min(NumCPU, 16)`, at least 1	Reads outside a transaction. Selected round-robin.
Snapshot	One per active read-only transaction	Reads inside a read-only transaction. Created on demand, closed when the transaction ends.

The pool size is compiled in and cannot be configured — loregd reads no configuration (§2.1).

4.1.1 One connection per handle #

Each Go database/sql handle has one physical connection. The write handle is reserved by a bound read-write transaction. Other mutations return busy rather than waiting for that reservation; per-hive gates coordinate admission and publication (§4.4).

It also means the snapshot connections are genuinely separate handles rather than borrowed pool entries, which is what keeps a long-running read-only transaction from consuming a pool slot.

4.1.2 What every connection carries #

Connection state is established on every physical connection, including one that replaces a connection discarded after cancellation:

journal_mode=wal on both databases, verified after being set.
foreign_keys=ON.
busy_timeout=0 — SQL lock conflicts return busy immediately (§4.4).
The hive's tmpfs database attached as volatile (§3.3).

Both stores have private-cache WAL readers. The volatile tables are created on the write connection; other connections attach the same file. A read-only transaction pins a snapshot of both stores before a commit can publish.

4.1.3 Which connection an operation uses #

Nine mutating operations are routed to the write connection through the transaction-aware write path: RSI_CREATE_KEY, RSI_WRITE_KEY, RSI_DROP_KEY, RSI_CREATE_ENTRY, RSI_HIDE_ENTRY, RSI_DELETE_ENTRY, RSI_SET_VALUE, RSI_DELETE_VALUE_ENTRY, and RSI_SET_BLANKET_TOMBSTONE.

Four read operations are routed to the read pool, or to the transaction's connection when one is bound: RSI_LOOKUP, RSI_ENUM_CHILDREN, RSI_READ_KEY, and RSI_QUERY_VALUES.

RSI_DELETE_LAYER and RSI_FLUSH take the hive's write connection directly rather than through the transaction-aware path, and open and commit work of their own. Neither can join a caller's transaction: RSI_FLUSH checkpoints a hive, and RSI_DELETE_LAYER spans every registered hive while a transaction binds to exactly one.

They do still consult the request's transaction id, for the two answers that do not require joining. A read-only transaction is declined with RSI_INVALID, as it is on every other mutating path. And because each hive allows a single write connection, RSI_DELETE_LAYER declines with RSI_TXN_BUSY while any transaction holds a pinned write connection rather than blocking on it forever — the same answer RSI_FLUSH gives for its own hive.

Edit this page