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