1mod 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
123pub(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
135pub(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
146pub(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
160pub(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
174fn sqlite_size_env(name: &str) -> Option<String> {
178 std::env::var_os(name).map(|raw| raw.to_string_lossy().into_owned())
179}
180
181pub(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; const 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
249pub(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#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize)]
269pub struct SearchMechanismSnapshot {
270 pub dispatches_by_backend_and_kind: BTreeMap<String, BTreeMap<String, u64>>,
274 pub note_candidate_hydration_rows: u64,
278}
279
280pub struct ConnectionPool {
294 writer: Arc<Mutex<ProgressConn>>,
295 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 checkpoint_ownership: CheckpointOwnershipGate,
309 pooled_writer_retired: AtomicBool,
314 writer_acquisition_counters: Arc<WriterAcquisitionCounters>,
319 write_admission: Arc<WriteAdmission>,
322 disk_guard_config: Option<EffectiveDiskGuardConfig>,
325 reader_acquisition_counters: ReaderAcquisitionCounters,
330 note_search_routes: NoteSearchRouteCounters,
332 reader_checkouts: Mutex<BTreeMap<Instant, usize>>,
333 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 read_only_open_target: Option<PathBuf>,
348 sql_bridge_reader_slots: Arc<Semaphore>,
349 sql_bridge_writer_slots: Arc<Semaphore>,
350 writer_task: OnceLock<Option<WriterTaskHandle>>,
355 writer_task_join: Mutex<Option<tokio::task::JoinHandle<()>>>,
363 writer_task_join_stored: AtomicBool,
368 origin: TxOrigin,
374 identity_path: Option<PathBuf>,
380 #[cfg(any(unix, windows))]
383 opened_file_identity: Option<DatabaseFileIdentity>,
384 opened_database_id: Option<uuid::Uuid>,
387 identity_registration: Option<PoolIdentityRegistration>,
390 timeout_sink_registration: Option<crate::timeout_sink::Registration>,
392 #[cfg(test)]
398 writer_task_spawn_count: std::sync::atomic::AtomicUsize,
399}
400
401impl Drop for ConnectionPool {
402 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;