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