pub struct PoolConfig {Show 20 fields
pub path: Option<PathBuf>,
pub code_map_vfs: Option<String>,
pub expected_file_identity: Option<DatabaseFileIdentity>,
pub max_readers: usize,
pub reader_max_age: Duration,
pub reader_max_ops: u64,
pub wal_mode: bool,
pub busy_timeout: Duration,
pub checkout_timeout: Duration,
pub reader_checkout_warn_after: Duration,
pub journal_size_limit_bytes: i64,
pub read_only: bool,
pub wal_ceiling: WalCeilingPolicy,
pub write_queue_enabled: Option<bool>,
pub write_queue_capacity: usize,
pub write_routing_strict: bool,
pub write_admission_deadline_ms: u64,
pub disk_guard_config: Option<EffectiveDiskGuardConfig>,
pub volume_lock_dir: Option<PathBuf>,
pub read_tx_max_age: Duration,
}Expand description
Configuration for the connection pool.
Fields§
§path: Option<PathBuf>Database path. None = in-memory (pool degrades to single connection).
code_map_vfs: Option<String>Registered native code-map VFS name; set only by the code-map constructor.
expected_file_identity: Option<DatabaseFileIdentity>File identity pinned by the caller before this pool opens SQLite. A mismatch is refused before identity initialization or WAL setup.
max_readers: usizeNumber of reader connections (default: min(num_cpus, 8)).
reader_max_age: DurationRetire a dedicated reader on return when its connection age exceeds
this duration. KHIVE_READER_MAX_AGE_SECS, default 300 seconds.
Does not expire an outstanding lease or recycle the shared writer.
reader_max_ops: u64Retire a dedicated reader on return after more than this many
successful checkouts. KHIVE_READER_MAX_OPS, default 5000.
Counts leases, not SQL statements; zero retires every returned lease.
wal_mode: boolWAL mode (must be true for pooling to work; default: true).
busy_timeout: DurationBusy timeout per connection (default: 30s).
Overridable via KHIVE_BUSY_TIMEOUT_SECS.
checkout_timeout: DurationTime to wait for a reader connection before returning an error (default: 5s).
For a writer it bounds only the pool-mutex wait. A writable file-backed
pool takes the volume lease first, bounded by the guard deadline
(disk_guard_deadline_ms, default 2000 ms), so the effective writer
wait under contention is the guard deadline, then checkout_timeout:
a 50 ms value here can still wait about 2 s, and a wait that ends at
the lease returns CapacityUnavailable with phase lock_contended rather than a
checkout timeout. Diagnostics report both bounds and their sum.
Overridable via KHIVE_CHECKOUT_TIMEOUT_SECS.
reader_checkout_warn_after: DurationWarn once per observed episode while an outstanding pooled checkout
exceeds this age. Captured from KHIVE_READER_CHECKOUT_WARN_SECS
(default: 10 seconds); this never cancels or closes a reader.
journal_size_limit_bytes: i64Maximum WAL journal size in bytes before SQLite resets the WAL.
Maps to PRAGMA journal_size_limit. Default: 64 MiB.
Overridable via KHIVE_JOURNAL_SIZE_LIMIT_BYTES.
read_only: boolOpen the database read-only (default: false).
When true, the pool’s writer connection is opened with
SQLITE_OPEN_READ_ONLY (no SQLITE_OPEN_CREATE, so a missing path is
rejected instead of created) and PRAGMA query_only = ON is set on
every connection that can execute SQL. Reader connections are already
opened read-only regardless of this flag.
wal_ceiling: WalCeilingPolicyADR-194 WAL active-extent ceiling and its resolved configuration source. Zero explicitly disables this independent policy.
write_queue_enabled: Option<bool>Route migrated store write paths through the single-writer
WriterTask channel (ADR-067 Component A) instead of the legacy
per-call pool-mutex/standalone-connection path. Enabled by default
for file-backed pools when unset; explicit override always wins.
That default is a compatibility-routing posture subordinate to
ADR-135 Amendment 1 and ADR-136 D1/D2 — the strict-routing default
flip has NOT happened.
The store layer resolves all of its routed write paths at write time;
the classification table in writer_task.rs remains the authoritative
inventory. This tranche does not claim the repository-wide
single-writer guarantee, and the strict default is still evidence-gated.
None means the caller expressed no preference: ConnectionPool::new
resolves it once path is known, defaulting to true for file-backed
pools and false for in-memory ones. Some(_) is an explicit
preference and always wins, in both directions, over that default.
An explicit Some(true) on an in-memory pool is accepted DELIBERATELY
and emits a warning before degrading to the legacy path — an in-memory
pool cannot host a writer task (writer_task::spawn’s
standalone-connection open fails); see
ConnectionPool::writer_task_handle and the
explicit_true_stays_on_for_memory_backed_pool test.
Overridable via KHIVE_WRITE_QUEUE ("1" or "true",
case-insensitive, sets Some(true); any other value sets Some(false);
unset leaves it None).
write_queue_capacity: usizeBounded channel capacity for the WriterTask write queue.
Overridable via KHIVE_WRITE_QUEUE_CAPACITY. Default: 256 pending
operations (ADR-067 Component A recommended default).
write_routing_strict: boolADR-136 D1: when true, every covered store write path that would
otherwise silently degrade to the legacy pool-mutex/standalone-
connection path on a missing or failed WriterTask handle instead
returns an error.
Exercises the store-layer routing tranche toward ADR-135 F2’s
strict-routing precondition without changing behavior for callers that
never set the env var.
Overridable via KHIVE_WRITE_ROUTING (value "strict",
case-insensitive; anything else, or unset, leaves this false).
write_admission_deadline_ms: u64Dedicated admission deadline (ADR-131 Decision 2) bounding ONLY the
wait for capacity on the WriterTask write queue —
WriterTaskHandle::send_bounded/send_top_level_bounded’s default
timeout. Distinct from checkout_timeout, which bounds reader/pool
checkout instead; the two authorities used to be conflated (#1382,
#1643) before this field existed.
Default: 2000 ms. Validated at ConnectionPool::new to fall in
[100, 10000] ms; a value outside that range is a configuration
error (SqliteError::InvalidConfig), never silently clamped into
range.
Overridable via KHIVE_WRITE_ADMISSION_DEADLINE_MS.
disk_guard_config: Option<EffectiveDiskGuardConfig>SQLite disk-reserve and guard-deadline policy for this pool. None
resolves the process environment when the pool opens.
volume_lock_dir: Option<PathBuf>Shared per-user directory for the volume advisory lock files.
PoolConfig::default resolves it with crate::default_volume_lock_dir
and leaves None when no directory can be resolved.
read_tx_max_age: DurationMaximum age an explicit cached-reader read transaction
(sql_bridge’s BEGIN-then-reuse path) may reach before its next use
is refused and it is rolled back instead of extending its WAL
snapshot further (#1846). Shares KHIVE_TX_MAX_AGE_SECS with the
ADR-091 Plank 1 visibility sweep in checkpoint.rs so one knob
governs both when an operator is warned about a stale reader and when
that reader’s snapshot is actually released.
Overridable via KHIVE_TX_MAX_AGE_SECS. Default: 120 seconds.