Skip to main content

khive_db/pool/
construction.rs

1//! Pool construction and initial connection admission.
2
3use std::collections::BTreeMap;
4use std::path::Path;
5use std::sync::atomic::{AtomicBool, AtomicU64};
6use std::sync::{Arc, OnceLock};
7
8use crossbeam_queue::ArrayQueue;
9use khive_storage::tx_registry::TxOrigin;
10use khive_storage::CapacityUnavailablePhase;
11use parking_lot::Mutex;
12use rusqlite::Connection;
13use tokio::sync::Semaphore;
14
15use crate::disk_guard_config::{resolve_disk_guard_config, DEFAULT_DISK_GUARD_DEADLINE_MS};
16use crate::error::SqliteError;
17#[cfg(any(unix, windows))]
18use crate::file_identity::database_file_identity;
19
20#[cfg(any(unix, windows))]
21use super::{claimed_file_identity, database_file_identity_if_exists, opened_sqlite_file_identity};
22use super::{
23    code_map, configure_writer_connection, deny_retired_writer, effective_reader_count,
24    initialize_database_id_with_admission, mint_db_identity, open_writer_connection,
25    read_database_id, read_only_open_target, refuse_home_data_store_in_tests,
26    validate_wal_ceiling_at_open, validate_write_admission_deadline, CheckpointOwnershipGate,
27    ConnectionPool, PoolConfig, PoolIdentityRegistration, ReaderAcquisitionCounters,
28    WriteAdmission, WriterAcquisitionCounters,
29};
30#[cfg(test)]
31use super::{run_identity_open_hook, IdentityOpenStage};
32
33enum ReadOnlyOpenMode {
34    FrozenSnapshot,
35    Live,
36}
37
38impl ConnectionPool {
39    /// Create a new connection pool.
40    ///
41    /// Opens 1 writer + N reader connections to the same database when pooling
42    /// is enabled. All connections are configured consistently (busy timeout,
43    /// foreign keys, cache, mmap, temp store). Writable in-memory databases and
44    /// writable non-WAL files fall back to single-connection mode. Read-only
45    /// files retain a dedicated reader regardless of journal mode.
46    pub fn new(config: PoolConfig) -> Result<Self, SqliteError> {
47        Self::new_with_read_only_open_mode(config, ReadOnlyOpenMode::FrozenSnapshot)
48    }
49
50    pub(crate) fn new_read_only_live(mut config: PoolConfig) -> Result<Self, SqliteError> {
51        config.read_only = true;
52        config.write_queue_enabled = Some(false);
53        Self::new_with_read_only_open_mode(config, ReadOnlyOpenMode::Live)
54    }
55
56    fn new_with_read_only_open_mode(
57        config: PoolConfig,
58        read_only_mode: ReadOnlyOpenMode,
59    ) -> Result<Self, SqliteError> {
60        refuse_home_data_store_in_tests(&config)?;
61        validate_write_admission_deadline(config.write_admission_deadline_ms)?;
62        if let Some(policy) = config.disk_guard_config {
63            policy.validate()?;
64        }
65        config.wal_ceiling.validate_static(
66            config.path.is_some(),
67            config.wal_mode,
68            config.read_only,
69        )?;
70        code_map::validate_pool(&config)?;
71        if config.path.is_some() && !config.read_only {
72            let lock_dir =
73                crate::disk_guard_config::require_volume_lock_dir(config.volume_lock_dir.clone())?;
74            if !lock_dir.is_absolute() {
75                return Err(SqliteError::CapacityUnavailable {
76                    phase: CapacityUnavailablePhase::Lock,
77                    message: "configured volume-lock directory is not absolute".to_string(),
78                });
79            }
80        }
81
82        // Resolve "no preference" (`None`) now that `path` is known: on for
83        // file-backed pools, off for in-memory ones. An explicit `Some(_)`
84        // preference is left untouched and always wins.
85        let mut config = config;
86        let inert_memory_queue_request =
87            config.path.is_none() && config.write_queue_enabled == Some(true);
88        config.write_queue_enabled =
89            Some(config.write_queue_enabled.unwrap_or(config.path.is_some()));
90        if inert_memory_queue_request {
91            tracing::warn!(target: "khive_db::pool",
92                "write queue explicitly requested for an in-memory pool; it is inert because \
93                 in-memory pools cannot host a writer task"
94            );
95        }
96
97        // Mint the physical identity before WAL classification or SQLite open.
98        // Every read-only connection below uses this same canonical path (or
99        // an immutable URI derived from it), so a symlink cannot split main-file
100        // resolution from sidecar resolution.
101        let (origin, identity_path) = match config.path.as_ref() {
102            Some(path) if config.code_map_vfs.is_some() => code_map::guarded_identity(path),
103            Some(path) => {
104                let (identity, canonical) = mint_db_identity(path)?;
105                (TxOrigin::Database(identity), Some(canonical))
106            }
107            None => (TxOrigin::Memory, None),
108        };
109        let (write_admission, disk_guard_config) = if !config.read_only {
110            if identity_path.as_deref().and_then(Path::parent).is_some() {
111                let disk_guard = match config.disk_guard_config {
112                    Some(policy) => policy,
113                    None => resolve_disk_guard_config(None, None)?,
114                };
115                disk_guard.validate()?;
116                if disk_guard.legacy_environment_present {
117                    tracing::warn!(target: "khive_db::pool",
118                        "legacy SQLite reserve setting is deprecated; \
119                         use KHIVE_SQLITE_DISK_RESERVE_BYTES"
120                    );
121                }
122                if disk_guard.reserve_bytes == 0 {
123                    tracing::warn!(target: "khive_db::pool",
124                        "SQLite disk reserve is explicitly zero; \
125                         new logical writes will not be floor-refused"
126                    );
127                }
128                (
129                    Arc::new(WriteAdmission::new(
130                        identity_path.clone(),
131                        disk_guard.reserve_bytes,
132                        disk_guard.guard_deadline_ms,
133                        config.volume_lock_dir.clone(),
134                    )?),
135                    Some(disk_guard),
136                )
137            } else {
138                (
139                    Arc::new(WriteAdmission::new(
140                        None,
141                        0,
142                        DEFAULT_DISK_GUARD_DEADLINE_MS,
143                        None,
144                    )?),
145                    None,
146                )
147            }
148        } else {
149            (
150                Arc::new(WriteAdmission::new(
151                    None,
152                    0,
153                    DEFAULT_DISK_GUARD_DEADLINE_MS,
154                    None,
155                )?),
156                None,
157            )
158        };
159        let read_only_open_target = match read_only_mode {
160            ReadOnlyOpenMode::FrozenSnapshot => {
161                read_only_open_target(&config, identity_path.as_deref())?
162            }
163            // Keep ordinary SQLite locking and change detection for a live WAL.
164            // Read-only flags and connection configuration still apply to every slot.
165            ReadOnlyOpenMode::Live => identity_path.clone(),
166        };
167        #[cfg(any(unix, windows))]
168        let identity_before_open = identity_path
169            .as_deref()
170            .map(database_file_identity_if_exists)
171            .transpose()?
172            .flatten();
173        #[cfg(any(unix, windows))]
174        claimed_file_identity::verify_before_open(&config, identity_before_open)?;
175        let retirement_connection = Connection::open_in_memory()?;
176        retirement_connection.authorizer(Some(deny_retired_writer))?;
177        // Declared first so a failed bootstrap closes SQLite before releasing its lease.
178        let mut initialization_lease = None;
179        let mut writer = open_writer_connection(
180            &config,
181            read_only_open_target.as_deref(),
182            identity_path.as_deref(),
183        )?;
184        validate_wal_ceiling_at_open(&writer, &config)?;
185        // The identity bootstrap can take a write lock before the remaining
186        // connection pragmas are configured. Honor the caller's wait bound.
187        writer.busy_timeout(config.busy_timeout)?;
188        // A read of main.sqlite_master forces SQLite's main file open without
189        // changing either database. Reject an already-swapped target before
190        // installing a nonce into a legacy or initially empty database.
191        let initial_database_id = if identity_path.is_some() {
192            read_database_id(&writer)?
193        } else {
194            None
195        };
196        #[cfg(test)]
197        if let Some(path) = identity_path.as_deref() {
198            run_identity_open_hook(
199                path,
200                IdentityOpenStage::AfterMainOpenBeforeFirstStat,
201                Some(&writer),
202            );
203        }
204        #[cfg(any(unix, windows))]
205        let identity_before_write = identity_path
206            .as_deref()
207            .map(database_file_identity)
208            .transpose()?;
209        #[cfg(any(unix, windows))]
210        if identity_before_open.is_some() && identity_before_open != identity_before_write {
211            return Err(SqliteError::InvalidData(
212                "database file identity changed while opening the pool".to_string(),
213            ));
214        }
215        #[cfg(any(unix, windows))]
216        if let Some(path) = identity_path.as_deref() {
217            let opened = opened_sqlite_file_identity(&writer, path)?;
218            if identity_before_write != Some(opened) {
219                return Err(SqliteError::InvalidData(
220                    "database file identity changed while opening the pool".to_string(),
221                ));
222            }
223        }
224        // A newly-created file must still belong to the volume captured from
225        // its parent before open, and an existing file must retain that volume.
226        write_admission.verify_current_volume()?;
227        let opened_database_id = if identity_path.is_some()
228            && !config.read_only
229            && initial_database_id.is_none()
230        {
231            match write_admission.check() {
232                Ok(()) => {
233                    initialization_lease = write_admission.acquire()?;
234                    match initialize_database_id_with_admission(&mut writer, Some(&write_admission))
235                    {
236                        Ok(id) => Some(id),
237                        Err(SqliteError::CapacityFloor { .. }) => None,
238                        Err(error) => return Err(error),
239                    }
240                }
241                // Recovery must be able to open this pool and its checkpoint
242                // connection below the reserve. Physical file pinning still
243                // applies; a later pool open can install the nonce.
244                Err(SqliteError::CapacityFloor { .. }) => None,
245                Err(error) => return Err(error),
246            }
247        } else {
248            initial_database_id
249        };
250        drop(initialization_lease.take());
251        #[cfg(test)]
252        if let Some(path) = identity_path.as_deref() {
253            run_identity_open_hook(
254                path,
255                IdentityOpenStage::AfterInitialIdentityWrite,
256                Some(&writer),
257            );
258        }
259        #[cfg(any(unix, windows))]
260        let opened_file_identity = identity_path
261            .as_deref()
262            .map(|path| opened_sqlite_file_identity(&writer, path))
263            .transpose()?;
264        #[cfg(any(unix, windows))]
265        if identity_before_write != opened_file_identity {
266            return Err(SqliteError::InvalidData(
267                "database file identity changed while opening the pool".to_string(),
268            ));
269        }
270        let wal_enabled = configure_writer_connection(&writer, &config)?;
271        let max_readers = effective_reader_count(&config, wal_enabled);
272
273        let readers = ArrayQueue::new(max_readers.max(1));
274
275        #[cfg(any(test, feature = "test-support"))]
276        let statement_observer = crate::statement_observer::StatementObserverHub::new()?;
277        #[cfg(any(test, feature = "test-support"))]
278        crate::statement_observer::install(&writer, &statement_observer)?;
279
280        let mut pool = Self {
281            writer: Arc::new(Mutex::new(writer)),
282            retirement_connection: Mutex::new(Some(retirement_connection)),
283            #[cfg(any(test, feature = "test-support"))]
284            statement_observer,
285            main_pool_generation: OnceLock::new(),
286            checkpoint_ownership: CheckpointOwnershipGate::new(),
287            pooled_writer_retired: AtomicBool::new(false),
288            writer_acquisition_counters: Arc::new(WriterAcquisitionCounters::default()),
289            write_admission,
290            disk_guard_config,
291            reader_acquisition_counters: ReaderAcquisitionCounters::default(),
292            note_search_routes: Default::default(),
293            reader_checkouts: Mutex::new(BTreeMap::new()),
294            search_dispatches: Mutex::new(BTreeMap::new()),
295            note_candidate_hydration_rows: AtomicU64::new(0),
296            readers,
297            max_readers,
298            config,
299            read_only_open_target,
300            sql_bridge_reader_slots: Arc::new(Semaphore::new(max_readers.max(1))),
301            sql_bridge_writer_slots: Arc::new(Semaphore::new(1)),
302            writer_task: OnceLock::new(),
303            writer_task_join: Mutex::new(None),
304            writer_task_join_stored: AtomicBool::new(false),
305            origin,
306            identity_path,
307            #[cfg(any(unix, windows))]
308            opened_file_identity,
309            opened_database_id,
310            identity_registration: None,
311            timeout_sink_registration: None,
312            #[cfg(test)]
313            writer_task_spawn_count: std::sync::atomic::AtomicUsize::new(0),
314        };
315
316        for _ in 0..pool.max_readers {
317            let conn = pool.open_pooled_reader()?;
318            pool.readers
319                .push(conn)
320                .expect("reader queue must have capacity during pool initialization");
321        }
322
323        // Read-only inspection must not create a diagnostic sink. Writable
324        // pools register with the writer for their resolved log directory.
325        if !pool.config.read_only {
326            pool.timeout_sink_registration = crate::timeout_sink::init(
327                pool.canonical_path().and_then(Path::parent),
328                &crate::timeout_sink::db_label(&pool),
329            )?;
330        }
331
332        pool.identity_registration = pool.canonical_path().map(PoolIdentityRegistration::new);
333        Ok(pool)
334    }
335}