Skip to main content

khive_db/
pool.rs

1//! Connection pool for SQLite: one exclusive writer, N concurrent readers.
2mod acquisition;
3mod connection_setup;
4mod construction;
5#[cfg(test)]
6mod external_writer_fixture;
7mod guards;
8mod identity;
9mod note_search_routes;
10mod pool_impl;
11mod reader_counters;
12mod standalone_checkpoint;
13#[cfg(test)]
14pub(crate) use external_writer_fixture::open_external_writer_fixture;
15
16pub(crate) use connection_setup::open_read_only_snapshot_connection;
17#[cfg(feature = "namespace-trigram-proto")]
18use connection_setup::register_namespace_trigram;
19#[cfg(test)]
20use connection_setup::sqlite_header_uses_wal;
21use connection_setup::{
22    close_connection_quietly, configure_reader_connection, configure_writer_connection,
23    current_journal_mode, effective_reader_count, open_reader_connection, open_writer_connection,
24    pool_exhausted_error, read_only_open_target, reader_connection_is_healthy,
25    reset_reader_connection, restore_shared_reader_state, validate_wal_ceiling_at_open,
26    writer_open_flags, writer_read_only_open_flags,
27};
28#[cfg(any(unix, windows))]
29use identity::database_file_identity_if_exists;
30#[cfg(test)]
31use identity::initialize_database_id;
32#[cfg(any(unix, windows))]
33pub(crate) use identity::opened_sqlite_file_identity;
34use identity::{initialize_database_id_with_admission, mint_db_identity, read_database_id};
35
36pub use crate::timeout_sink::{TimeoutSinkCloseError, TimeoutSinkCloseHandle};
37use guards::{PooledReader, ReaderLease};
38pub(crate) use guards::{ReaderAdmission, SharedReaderTransactionGuard};
39pub use guards::{ReaderGuard, ReaderRow};
40use note_search_routes::NoteSearchRouteCounters;
41pub use note_search_routes::{NoteSearchFallbackCause, NoteSearchRouteSnapshot};
42use reader_counters::ReaderAcquisitionCounters;
43pub use reader_counters::ReaderAcquisitionSnapshot;
44pub(crate) use reader_counters::StandaloneReaderPurpose;
45pub(crate) use standalone_checkpoint::CheckpointFile;
46pub use standalone_checkpoint::StandaloneCheckpoint;
47
48mod code_map;
49mod sql_functions;
50#[cfg(test)]
51pub(crate) use sql_functions::register_rfc3339_key;
52use sql_functions::{register_read_functions, register_writer_clock};
53pub(crate) use sql_functions::{rfc3339_instant_key, strict_rfc3339_key};
54#[path = "pool/identity_registry.rs"]
55mod identity_registry;
56#[cfg(any(test, feature = "test-support"))]
57#[path = "pool/test_volume_lock_dir.rs"]
58mod test_volume_lock_dir;
59#[path = "pool/write_units.rs"]
60mod write_units;
61#[path = "pool/writer_acquisition.rs"]
62mod writer_acquisition;
63#[cfg(test)]
64use identity_registry::pool_identity_suffix;
65use identity_registry::PoolIdentityRegistration;
66#[cfg(any(test, feature = "test-support"))]
67use test_volume_lock_dir::test_volume_lock_dir;
68#[cfg(test)]
69use write_units::STARTUP_SPACE_PROBE;
70pub use write_units::{CheckpointGuard, CheckpointResult, WriterAcquisitionSnapshot, WriterGuard};
71pub(crate) use write_units::{
72    PooledAutocommitWriteUnit, PooledTransactionWriteUnit, StandaloneWriteUnit, WriteAdmission,
73    WriterAcquisitionCounters,
74};
75
76use crossbeam_queue::ArrayQueue;
77use parking_lot::{Condvar, Mutex};
78use rusqlite::hooks::{AuthContext, Authorization};
79use rusqlite::{Connection, OpenFlags};
80use serde::Serialize;
81use sha2::{Digest, Sha256};
82#[cfg(test)]
83use std::cell::Cell;
84use std::collections::{BTreeMap, HashMap};
85use std::fs;
86use std::path::{Path, PathBuf};
87use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
88use std::sync::{Arc, OnceLock};
89#[cfg(test)]
90use std::thread;
91use std::time::{Duration, Instant};
92use tokio::sync::Semaphore;
93
94#[cfg(test)]
95use crate::database_owner_identity::DatabaseOwnerIdentityError;
96use crate::disk_guard::{LeaseRefusal, VolumeIdentity, VolumeLease};
97use crate::disk_guard_config::{EffectiveDiskGuardConfig, DEFAULT_DISK_GUARD_DEADLINE_MS};
98use crate::error::SqliteError;
99#[cfg(all(test, any(unix, windows)))]
100use crate::file_identity::database_file_identity;
101#[cfg(any(unix, windows))]
102use crate::file_identity::DatabaseFileIdentity;
103use crate::writer_task::{execute_wrapped_transaction, WriterTaskHandle};
104use khive_storage::error::StorageError;
105use khive_storage::tx_registry::TxOrigin;
106use khive_storage::CapacityUnavailablePhase;
107use khive_storage::StorageCapability;
108
109mod claimed_file_identity;
110
111#[cfg(unix)]
112mod claimed_file_observer;
113
114#[cfg(unix)]
115pub use claimed_file_observer::initialize as initialize_claimed_file_observer;
116
117#[cfg(all(test, unix))]
118#[path = "pool/claimed_file_identity_tests.rs"]
119mod claimed_file_identity_tests;
120
121/// Default SQLite page cache per pooled connection, in KiB.
122///
123/// Every connection keeps its own page cache on the process heap, so a
124/// process's ceiling is this value times its open connections, and a daemon
125/// serving several databases holds dozens of them. Pages the cache drops are
126/// re-read from the operating system's file cache, which the kernel reclaims
127/// on its own. `KHIVE_SQLITE_CACHE_KIB` overrides it within
128/// `SQLITE_CACHE_KIB_RANGE`.
129pub(crate) const DEFAULT_SQLITE_CACHE_KIB: i64 = 8 * 1024;
130pub(crate) const SQLITE_CACHE_KIB_RANGE: std::ops::RangeInclusive<i64> = 512..=1_048_576;
131const SQLITE_CACHE_KIB_ENV: &str = "KHIVE_SQLITE_CACHE_KIB";
132
133/// Default SQLite memory-map window per pooled connection, in bytes.
134///
135/// Mapped pages are clean and file-backed: the kernel drops them under memory
136/// pressure without writing them anywhere. Reads past the window go through
137/// the page cache above instead. `KHIVE_SQLITE_MMAP_BYTES` overrides it
138/// within `SQLITE_MMAP_BYTES_RANGE`; `0` turns memory-mapped reads off.
139pub(crate) const DEFAULT_SQLITE_MMAP_BYTES: i64 = 1 << 30;
140pub(crate) const SQLITE_MMAP_BYTES_RANGE: std::ops::RangeInclusive<i64> = 0..=(1 << 40);
141const SQLITE_MMAP_BYTES_ENV: &str = "KHIVE_SQLITE_MMAP_BYTES";
142const DEFAULT_READER_CAP: usize = 8;
143
144/// The `cache_size` pragma value every pooled connection is configured with
145/// (negative, so SQLite reads it as KiB), resolved once per process.
146pub(crate) fn sqlite_cache_size_pragma() -> i64 {
147    static KIB: OnceLock<i64> = OnceLock::new();
148    -*KIB.get_or_init(|| {
149        sqlite_size_setting(
150            SQLITE_CACHE_KIB_ENV,
151            sqlite_size_env(SQLITE_CACHE_KIB_ENV).as_deref(),
152            DEFAULT_SQLITE_CACHE_KIB,
153            &SQLITE_CACHE_KIB_RANGE,
154        )
155    })
156}
157
158/// The `mmap_size` pragma value every pooled connection is configured with,
159/// resolved once per process.
160pub(crate) fn sqlite_mmap_size_pragma() -> i64 {
161    static BYTES: OnceLock<i64> = OnceLock::new();
162    *BYTES.get_or_init(|| {
163        sqlite_size_setting(
164            SQLITE_MMAP_BYTES_ENV,
165            sqlite_size_env(SQLITE_MMAP_BYTES_ENV).as_deref(),
166            DEFAULT_SQLITE_MMAP_BYTES,
167            &SQLITE_MMAP_BYTES_RANGE,
168        )
169    })
170}
171
172/// Reads a size setting with `var_os`, not `var`: a set value that is not valid
173/// Unicode still counts as set, so it reaches the range check and is logged
174/// rather than silently taking the default.
175fn sqlite_size_env(name: &str) -> Option<String> {
176    std::env::var_os(name).map(|raw| raw.to_string_lossy().into_owned())
177}
178
179/// An unset setting takes the default. A set value that is not an integer
180/// inside `range` also takes the default, and says so in the log, because a
181/// typo in a memory setting must not stop the store from opening.
182pub(crate) fn sqlite_size_setting(
183    name: &str,
184    raw: Option<&str>,
185    default: i64,
186    range: &std::ops::RangeInclusive<i64>,
187) -> i64 {
188    let Some(raw) = raw else {
189        return default;
190    };
191    match raw.parse::<i64>() {
192        Ok(value) if range.contains(&value) => value,
193        _ => {
194            tracing::warn!(
195                setting = name,
196                value = raw,
197                default,
198                min = *range.start(),
199                max = *range.end(),
200                "ignoring a SQLite size setting outside its range; using the default"
201            );
202            default
203        }
204    }
205}
206
207const DEFAULT_JOURNAL_SIZE_LIMIT_BYTES: i64 = 67_108_864; // 64 MiB
208const DEFAULT_WRITE_QUEUE_CAPACITY: usize = 256;
209const DATABASE_ID_TABLE: &str = "_khive_database_identity";
210static NEXT_MAIN_POOL_GENERATION: AtomicU64 = AtomicU64::new(1);
211
212#[cfg(test)]
213#[derive(Clone, Copy, PartialEq, Eq)]
214enum IdentityOpenStage {
215    AfterMainOpenBeforeFirstStat,
216    AfterInitialIdentityWrite,
217    BeforeStandaloneOpen,
218    AfterStandaloneOpen,
219}
220
221#[cfg(test)]
222type IdentityOpenHook = Box<dyn Fn(&Path, IdentityOpenStage, Option<&Connection>)>;
223
224#[cfg(test)]
225thread_local! {
226    static IDENTITY_OPEN_HOOK: std::cell::RefCell<Option<IdentityOpenHook>> =
227        const { std::cell::RefCell::new(None) };
228}
229
230#[cfg(test)]
231fn run_identity_open_hook(path: &Path, stage: IdentityOpenStage, conn: Option<&Connection>) {
232    IDENTITY_OPEN_HOOK.with(|hook| {
233        if let Some(hook) = hook.borrow().as_ref() {
234            hook(path, stage, conn);
235        }
236    });
237}
238
239#[path = "pool/admission.rs"]
240mod admission;
241use admission::CheckpointOwnershipGate;
242pub use admission::RuntimeWriteOperation;
243pub(crate) use admission::FALLBACK_WAL_AUTOCHECKPOINT_PAGES;
244#[cfg(test)]
245use admission::{CheckpointConnectionConfigPause, CheckpointOwnership};
246
247fn deny_retired_writer(_context: AuthContext<'_>) -> Authorization {
248    Authorization::Deny
249}
250
251mod config;
252
253pub(crate) use config::TEST_HARNESS_ENV;
254use config::{refuse_home_data_store_in_tests, validate_write_admission_deadline};
255pub use config::{PoolConfig, WalCeilingPolicy, WalCeilingSource};
256
257/// Pool-scoped counters for ADR-166's search mechanism guards.
258#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize)]
259pub struct SearchMechanismSnapshot {
260    /// Coordinator calls actually issued to each registered backend, keyed by
261    /// the request's canonical kind. A backend skipped by served-kind routing
262    /// has no entry for that kind.
263    pub dispatches_by_backend_and_kind: BTreeMap<String, BTreeMap<String, u64>>,
264    /// Candidate note rows fetched after the text/vector fusion and fresh-tail
265    /// merge, including rows later filtered as deleted. Result metadata fetched
266    /// later by the KG handler is excluded.
267    pub note_candidate_hydration_rows: u64,
268}
269
270/// A read-write connection pool for SQLite.
271///
272/// Architecture:
273/// - 1 writer connection protected by a Mutex (exclusive access)
274/// - N reader connections in a lock-free queue (concurrent access)
275/// - All connections share the same database file in WAL mode
276///
277/// Writable in-memory databases, or writable file databases when WAL mode is
278/// disabled/unavailable, degrade to single-connection mode and route all
279/// operations through the writer connection. A file-backed read-only pool
280/// always retains at least one dedicated read-only connection: rollback-journal
281/// snapshots do not need WAL to support concurrent readers, and inspection must
282/// never alias a read onto the query-only writer slot.
283pub struct ConnectionPool {
284    writer: Arc<Mutex<Connection>>,
285    // Prepared before admission so terminal cleanup cannot fail while allocating a replacement.
286    retirement_connection: Mutex<Option<Connection>>,
287    #[cfg(any(test, feature = "test-support"))]
288    statement_observer: Arc<crate::statement_observer::StatementObserverHub>,
289    main_pool_generation: OnceLock<u64>,
290    /// Three-state gate for whether the ADR-091 scheduled task has claimed
291    /// routine WAL reclamation for this pool. Until claimed, every
292    /// writer-capable connection keeps a bounded SQLite autocheckpoint
293    /// ([`FALLBACK_WAL_AUTOCHECKPOINT_PAGES`]) so a writable pool without a
294    /// checkpoint task cannot grow its WAL without bound. After
295    /// [`Self::claim_checkpoint_ownership`], writer-capable connections open
296    /// with `wal_autocheckpoint = 0` and routine checkpoint I/O stays off
297    /// application commit paths.
298    checkpoint_ownership: CheckpointOwnershipGate,
299    /// Fail-closed guard for the legacy pool-mutex writer. A transaction
300    /// owner retires this connection after a body panic or when it cannot
301    /// prove that finalization restored autocommit mode; subsequent checkouts
302    /// must never reuse it.
303    pooled_writer_retired: AtomicBool,
304    /// Process-local writer acquisition counters shared with the pool's
305    /// lifetime-owned writer task. Keeping the counters at the actual
306    /// acquisition boundaries means new verbs inherit instrumentation without
307    /// per-verb classification (ADR-133 D8 / issue #1389).
308    writer_acquisition_counters: Arc<WriterAcquisitionCounters>,
309    /// Shared with the long-lived writer task so it can resample at every
310    /// dequeued request rather than only when its connection is opened.
311    write_admission: Arc<WriteAdmission>,
312    /// Effective source and values captured at open for diagnostic reporting;
313    /// the live volume identifier is deliberately resolved separately.
314    disk_guard_config: Option<EffectiveDiskGuardConfig>,
315    /// Pool-scoped reader route, saturation, and hold-lifecycle counters.
316    /// Instrumentation lives at the acquisition boundary so every typed
317    /// store and raw-SQL caller inherits it without per-verb bookkeeping
318    /// (ADR-165 Slice 2 / ADR-166 G2).
319    reader_acquisition_counters: ReaderAcquisitionCounters,
320    /// Note-search route counters belong to this opened pool, not a logical ID.
321    note_search_routes: NoteSearchRouteCounters,
322    reader_checkouts: Mutex<BTreeMap<Instant, usize>>,
323    /// ADR-166 G4/G5 process-lifetime mechanism counters for this physical
324    /// backend. Backend IDs remain separate even when aliases share a pool.
325    search_dispatches: Mutex<BTreeMap<String, BTreeMap<String, u64>>>,
326    note_candidate_hydration_rows: AtomicU64,
327    readers: ArrayQueue<Box<PooledReader>>,
328    max_readers: usize,
329    config: PoolConfig,
330    /// Canonical physical target used by every connection in a file-backed
331    /// read-only pool. Classification and open must share this exact spelling:
332    /// deriving WAL sidecars from a configured symlink while SQLite follows it
333    /// to another file can hide committed frames or a live writable `-shm`.
334    /// The value is an `immutable=1` URI only for a clean, checkpointed WAL;
335    /// rollback-journal databases and frozen WAL+SHM snapshots retain the
336    /// canonical ordinary path and SQLite locking/change detection.
337    read_only_open_target: Option<PathBuf>,
338    sql_bridge_reader_slots: Arc<Semaphore>,
339    sql_bridge_writer_slots: Arc<Semaphore>,
340    /// The pool-wide ADR-067 Component A writer task, spawned lazily and at
341    /// most once per pool (per DB file) via [`Self::writer_task_handle`] —
342    /// see that method's doc comment for why this lives here rather than on
343    /// each store.
344    writer_task: OnceLock<Option<WriterTaskHandle>>,
345    /// The `tokio::spawn` JoinHandle of the writer task above, stored by
346    /// [`crate::writer_task::spawn`] so short-lived callers (batch CLI
347    /// paths) can await the task's exit — and therefore its connection's
348    /// close-time WAL checkpoint — before treating the database file state
349    /// as settled. Long-running callers never take it; dropping an untaken
350    /// JoinHandle detaches the task, which is exactly the pre-existing
351    /// behavior.
352    writer_task_join: Mutex<Option<tokio::task::JoinHandle<()>>>,
353    /// Monotonic "a writer-task JoinHandle was stored at least once" flag
354    /// backing [`Self::set_writer_task_join`]'s at-most-once guard: it holds
355    /// the invariant even after [`Self::take_writer_task_join`] empties the
356    /// slot, so a second store never re-arms it.
357    writer_task_join_stored: AtomicBool,
358    /// This pool's ADR-091 backend-scoped attribution origin, minted exactly
359    /// once at construction (see [`mint_db_identity`]): `Database(_)` for a
360    /// file-backed pool, `Memory` for an in-memory pool. Every
361    /// `tx_registry::register_scoped` call site in this crate reaches its
362    /// origin through [`Self::origin`] rather than re-deriving it.
363    origin: TxOrigin,
364    /// The canonical path `origin`'s `DbIdentity` was minted from, `None` for
365    /// an in-memory pool. `DbIdentity` is deliberately opaque (no path
366    /// accessor) — filesystem consumers that need the actual path (sidecar
367    /// derivation) use this, the same canonical value the identity was
368    /// minted from, via [`Self::canonical_path`].
369    identity_path: Option<PathBuf>,
370    /// The physical file SQLite opened, checked against the canonical path.
371    /// Later reader and standalone opens must retain this identity.
372    #[cfg(any(unix, windows))]
373    opened_file_identity: Option<DatabaseFileIdentity>,
374    /// A persistent nonce read through SQLite's opened main database, rather
375    /// than through the pathname that may have been replaced during open.
376    opened_database_id: Option<uuid::Uuid>,
377    /// Registered only after every connection opens successfully. RAII removes
378    /// the path when the last pool for it drops, including failed construction.
379    identity_registration: Option<PoolIdentityRegistration>,
380    /// Releases pool ownership without implicitly shutting down diagnostics.
381    timeout_sink_registration: Option<crate::timeout_sink::Registration>,
382    /// Test-only instrumentation: counts how many times the writer-task
383    /// init closure actually ran. Must never exceed 1 per pool no matter how
384    /// many stores are constructed over it — that is the invariant
385    /// `OnceLock::get_or_init` exists to guarantee, and what
386    /// `pool.rs`'s and `entity_tests.rs`'s one-writer-per-pool tests assert.
387    #[cfg(test)]
388    writer_task_spawn_count: std::sync::atomic::AtomicUsize,
389}
390
391impl Drop for ConnectionPool {
392    /// Close every read-only reader before the fields below it drop in
393    /// declaration order (`writer` first, `readers` well before
394    /// `writer_task`). A read-only connection cannot take the EXCLUSIVE lock
395    /// SQLite needs to checkpoint on close, so if a reader were left to close
396    /// last, WAL mode would leave `-wal`/`-shm` behind. Draining `readers`
397    /// here, before that field-order drop runs, makes the writable `writer`
398    /// connection close after every reader instead of before it.
399    fn drop(&mut self) {
400        while let Some(conn) = self.readers.pop() {
401            drop(conn);
402        }
403    }
404}
405
406#[cfg(test)]
407#[path = "runtime_write_routing_tests.rs"]
408mod runtime_write_routing_tests;
409
410#[cfg(test)]
411#[path = "database_owner_identity_pool_tests.rs"]
412mod database_owner_identity_pool_tests;
413
414#[cfg(test)]
415#[path = "pool_tests.rs"]
416mod tests;
417
418#[cfg(test)]
419#[path = "pool/recycling_tests.rs"]
420mod recycling_tests;
421
422#[cfg(all(test, any(unix, windows)))]
423#[path = "pool_identity_admission_tests.rs"]
424mod identity_admission_tests;