1use std::path::Path;
4use std::sync::atomic::Ordering;
5use std::sync::Arc;
6use std::time::{Duration, Instant};
7
8use khive_storage::error::StorageError;
9use khive_storage::tx_registry::TxOrigin;
10use khive_storage::StorageCapability;
11use rusqlite::{Connection, OpenFlags};
12use tokio::sync::Semaphore;
13
14use crate::database_owner_identity::{DatabaseOwnerIdentity, DatabaseOwnerIdentityError};
15use crate::disk_guard_config::EffectiveDiskGuardConfig;
16#[cfg(test)]
17use crate::disk_guard_config::{DiskGuardConfigSource, DEFAULT_DISK_GUARD_DEADLINE_MS};
18use crate::error::SqliteError;
19#[cfg(any(unix, windows))]
20use crate::file_identity::{database_file_identity, DatabaseFileIdentity};
21use crate::writer_task::WriterTaskHandle;
22
23#[cfg(any(unix, windows))]
24use super::opened_sqlite_file_identity;
25#[cfg(doc)]
26use super::pool_exhausted_error;
27#[cfg(feature = "namespace-trigram-proto")]
28use super::register_namespace_trigram;
29use super::{
30 claimed_file_identity, close_connection_quietly, configure_reader_connection,
31 current_journal_mode, open_reader_connection, read_database_id, reader_connection_is_healthy,
32 register_read_functions, register_writer_clock, reset_reader_connection, CheckpointFile,
33 ConnectionPool, PoolConfig, PoolIdentityRegistration, PooledReader, ReaderAcquisitionSnapshot,
34 ReaderGuard, RuntimeWriteOperation, SearchMechanismSnapshot, StandaloneCheckpoint,
35 StandaloneReaderPurpose, StandaloneWriteUnit, WriteAdmission, WriterAcquisitionCounters,
36 WriterAcquisitionSnapshot, NEXT_MAIN_POOL_GENERATION,
37};
38#[cfg(test)]
39use super::{run_identity_open_hook, IdentityOpenStage};
40
41impl ConnectionPool {
42 pub fn writer_acquisition_snapshot(&self) -> WriterAcquisitionSnapshot {
45 self.writer_acquisition_counters
46 .snapshot(self.write_admission.lease_timeouts())
47 }
48
49 pub fn record_search_dispatch(&self, backend_id: &str, requested_kind: &str) {
53 let mut dispatches = self.search_dispatches.lock();
54 let count = dispatches
55 .entry(backend_id.to_owned())
56 .or_default()
57 .entry(requested_kind.to_owned())
58 .or_default();
59 *count = count.saturating_add(1);
60 }
61
62 pub fn record_note_candidate_hydration_row(&self) {
66 let _ = self.note_candidate_hydration_rows.fetch_update(
67 Ordering::Relaxed,
68 Ordering::Relaxed,
69 |current| Some(current.saturating_add(1)),
70 );
71 }
72
73 pub fn search_mechanism_snapshot(&self) -> SearchMechanismSnapshot {
75 SearchMechanismSnapshot {
76 dispatches_by_backend_and_kind: self.search_dispatches.lock().clone(),
77 note_candidate_hydration_rows: self
78 .note_candidate_hydration_rows
79 .load(Ordering::Relaxed),
80 }
81 }
82
83 pub fn reader_acquisition_snapshot(&self) -> ReaderAcquisitionSnapshot {
87 self.reader_acquisition_counters.snapshot(
88 self.max_readers.max(1),
89 self.sql_bridge_reader_slots.available_permits(),
90 )
91 }
92
93 pub(crate) fn record_reader_admission_timeout(&self) {
97 self.reader_acquisition_counters.record_checkout_timeout();
98 }
99
100 pub(crate) fn record_reader_query_error(&self, error: &StorageError) {
106 if crate::read_cancellation::storage_error_sqlite_code(error)
107 == Some(rusqlite::ErrorCode::DatabaseBusy)
108 {
109 self.reader_acquisition_counters.record_busy_timeout();
110 }
111 }
112
113 pub(crate) fn writer_acquisition_counters(&self) -> Arc<WriterAcquisitionCounters> {
115 Arc::clone(&self.writer_acquisition_counters)
116 }
117
118 pub(crate) fn write_admission(&self) -> Arc<WriteAdmission> {
119 Arc::clone(&self.write_admission)
120 }
121
122 pub fn effective_disk_guard_config(&self) -> Option<EffectiveDiskGuardConfig> {
123 self.disk_guard_config
124 }
125
126 #[cfg(test)]
127 pub(crate) fn set_test_write_admission(
128 &mut self,
129 floor_bytes: u64,
130 probe: impl Fn(&Path) -> std::io::Result<u64> + Send + Sync + 'static,
131 ) {
132 let database_path = if self.config.read_only {
133 None
134 } else {
135 self.canonical_path().map(Path::to_path_buf)
136 };
137 let admission = Arc::new(
138 WriteAdmission::new(
139 database_path,
140 floor_bytes,
141 DEFAULT_DISK_GUARD_DEADLINE_MS,
142 self.config.volume_lock_dir.clone(),
143 )
144 .expect("test admission volume identity"),
145 );
146 admission.set_test_space_probe(probe);
147 self.write_admission = admission;
148 if self.canonical_path().is_some() && !self.config.read_only {
149 self.disk_guard_config = Some(EffectiveDiskGuardConfig {
150 reserve_bytes: floor_bytes,
151 guard_deadline_ms: DEFAULT_DISK_GUARD_DEADLINE_MS,
152 reserve_source: DiskGuardConfigSource::Backend,
153 deadline_source: DiskGuardConfigSource::Default,
154 legacy_environment_present: false,
155 });
156 }
157 }
158
159 pub fn available_readers(&self) -> usize {
161 self.readers.len()
162 }
163
164 pub fn max_readers(&self) -> usize {
166 self.max_readers
167 }
168
169 pub fn oldest_checkout_age(&self) -> Option<Duration> {
174 self.oldest_checkout_age_at(Instant::now())
175 }
176
177 pub(crate) fn oldest_checkout_age_at(&self, now: Instant) -> Option<Duration> {
178 self.reader_checkouts
179 .lock()
180 .first_key_value()
181 .map(|(started, _)| now.saturating_duration_since(*started))
182 }
183
184 pub(super) fn begin_reader_checkout(&self) -> Instant {
185 let started = Instant::now();
186 *self.reader_checkouts.lock().entry(started).or_default() += 1;
188 started
189 }
190
191 pub(super) fn finish_reader_checkout(&self, started: Instant) {
192 let mut checkouts = self.reader_checkouts.lock();
193 if let Some(count) = checkouts.get_mut(&started) {
194 *count -= 1;
195 if *count == 0 {
196 checkouts.remove(&started);
197 }
198 }
199 }
200
201 pub fn config(&self) -> &PoolConfig {
203 &self.config
204 }
205
206 #[cfg(any(test, feature = "test-support"))]
216 pub fn observe_test_statement_starts(
217 &self,
218 limit: usize,
219 ) -> Result<crate::statement_observer::StatementStartObservation, SqliteError> {
220 self.statement_observer.observe(limit)
221 }
222
223 pub fn main_pool_generation(&self) -> u64 {
227 *self.main_pool_generation.get_or_init(|| {
228 NEXT_MAIN_POOL_GENERATION
229 .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |next| {
230 next.checked_add(1)
231 })
232 .expect("main pool generation exhausted")
233 })
234 }
235
236 pub(crate) fn reader_admission_timeout(&self, operation: &'static str) -> StorageError {
240 StorageError::AdmissionTimeout {
241 operation: operation.into(),
242 timeout_ms: u64::try_from(self.config.checkout_timeout.as_millis()).unwrap_or(u64::MAX),
243 pool_identity: Some(
244 self.identity_registration
245 .as_ref()
246 .map(PoolIdentityRegistration::label)
247 .unwrap_or_else(|| ":memory:".to_string()),
248 ),
249 }
250 }
251
252 pub(crate) fn resolve_reader_checkout<'p>(
271 &self,
272 capability: StorageCapability,
273 operation: &'static str,
274 outcome: Result<Option<ReaderGuard<'p>>, SqliteError>,
275 ) -> Result<ReaderGuard<'p>, StorageError> {
276 match outcome {
277 Ok(Some(mut guard)) => {
278 guard.label_operation(operation);
279 Ok(guard)
280 }
281 Ok(None) => Err(self.reader_checkout_refusal(capability, operation, None)),
282 Err(error) => Err(self.reader_checkout_refusal(capability, operation, Some(error))),
283 }
284 }
285
286 pub(super) fn reader_checkout_refusal(
291 &self,
292 capability: StorageCapability,
293 operation: &'static str,
294 error: Option<SqliteError>,
295 ) -> StorageError {
296 let Some(error) = error else {
297 return StorageError::Timeout {
298 operation: operation.into(),
299 };
300 };
301 let is_pool_exhausted = matches!(
302 &error,
303 SqliteError::Rusqlite(rusqlite::Error::SqliteFailure(code, _))
304 if code.code == rusqlite::ErrorCode::DatabaseBusy
305 );
306 if is_pool_exhausted {
307 self.reader_admission_timeout(operation)
308 } else {
309 StorageError::driver(capability, operation, error)
310 }
311 }
312
313 pub(crate) fn sql_bridge_reader_slots(&self) -> Arc<Semaphore> {
316 Arc::clone(&self.sql_bridge_reader_slots)
317 }
318
319 pub(crate) fn sql_bridge_writer_slots(&self) -> Arc<Semaphore> {
321 Arc::clone(&self.sql_bridge_writer_slots)
322 }
323
324 pub fn retirement_writer_holds(&self) -> usize {
329 usize::from(self.writer.is_locked())
330 + usize::from(self.sql_bridge_writer_slots.available_permits() == 0)
331 }
332
333 pub fn origin(&self) -> TxOrigin {
339 self.origin.clone()
340 }
341
342 pub fn canonical_path(&self) -> Option<&Path> {
348 self.identity_path.as_deref()
349 }
350
351 #[cfg(unix)]
353 pub fn opened_file_identity(&self) -> Option<(u64, u64)> {
354 self.opened_file_identity
355 .map(DatabaseFileIdentity::unix_parts)
356 }
357
358 #[cfg(any(unix, windows))]
361 pub fn opened_file_identity_record(&self) -> Option<DatabaseFileIdentity> {
362 self.opened_file_identity
363 }
364
365 pub fn database_owner_identity(
370 &self,
371 ) -> Result<DatabaseOwnerIdentity, DatabaseOwnerIdentityError> {
372 if self.identity_path.is_none() {
373 return Err(DatabaseOwnerIdentityError::InMemory);
374 }
375 #[cfg(any(unix, windows))]
376 {
377 let durable_id = self
378 .opened_database_id
379 .ok_or(DatabaseOwnerIdentityError::DurableIdentityUnavailable)?;
380 let file_identity = self
381 .opened_file_identity
382 .ok_or(DatabaseOwnerIdentityError::PhysicalIdentityUnavailable)?;
383 Ok(DatabaseOwnerIdentity {
384 durable_id,
385 file_identity,
386 })
387 }
388 #[cfg(not(any(unix, windows)))]
389 {
390 Err(DatabaseOwnerIdentityError::UnsupportedPlatform)
391 }
392 }
393
394 pub fn verify_database_owner(
396 &self,
397 expected: &DatabaseOwnerIdentity,
398 ) -> Result<(), DatabaseOwnerIdentityError> {
399 self.database_owner_identity()?.verify_owner(expected)
400 }
401
402 pub fn write_queue_active(&self) -> bool {
414 debug_assert!(
415 self.config.write_queue_enabled.is_some(),
416 "write_queue_enabled must be resolved to Some(..) by ConnectionPool::new \
417 before any write_queue_active read"
418 );
419 self.config.write_queue_enabled.unwrap_or(false) && self.config.path.is_some()
420 }
421
422 pub fn writer_task_join_was_stored(&self) -> bool {
428 self.writer_task_join_stored.load(Ordering::SeqCst)
429 }
430
431 pub fn writer_task_handle(&self) -> Result<Option<WriterTaskHandle>, StorageError> {
455 debug_assert!(
463 self.config.write_queue_enabled.is_some(),
464 "write_queue_enabled must be resolved to Some(..) by ConnectionPool::new \
465 before any writer_task_handle read"
466 );
467 if !self.config.write_queue_enabled.unwrap_or(false) {
468 return Ok(None);
469 }
470 if let Some(existing) = self.writer_task.get() {
473 return Ok(existing.clone());
474 }
475 if tokio::runtime::Handle::try_current().is_err() {
479 return Err(StorageError::WriterTaskNoRuntime);
480 }
481 Ok(self
482 .writer_task
483 .get_or_init(|| {
484 #[cfg(test)]
485 self.writer_task_spawn_count
486 .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
487
488 match crate::writer_task::spawn(self, self.config.write_queue_capacity) {
489 Ok(handle) => Some(handle),
490 Err(e) => {
491 tracing::warn!(target: "khive_db::pool",
492 error = %e,
493 "KHIVE_WRITE_QUEUE=1 but the writer task failed to spawn; \
494 writes fall back to the pool-mutex path"
495 );
496 None
497 }
498 }
499 })
500 .clone())
501 }
502
503 pub(crate) fn writer_admission_snapshot(
504 &self,
505 ) -> Result<crate::writer_admission_metrics::Snapshot, &'static str> {
506 if !self.config.write_queue_enabled.unwrap_or(false) {
507 return Err("writer_queue_disabled");
508 }
509 match self.writer_task.get() {
510 None => Err("writer_not_initialized"),
511 Some(None) => Err("writer_unavailable"),
512 Some(Some(handle)) => handle
513 .admission_snapshot()
514 .map_err(|reason| reason.reason()),
515 }
516 }
517
518 pub(crate) fn writer_task_for_write(
528 &self,
529 cached: Option<&WriterTaskHandle>,
530 operation: &'static str,
531 ) -> Result<Option<WriterTaskHandle>, StorageError> {
532 let handle = match cached {
533 Some(handle) => Some(handle.clone()),
534 None => match self.writer_task_handle() {
535 Ok(handle) => handle,
536 Err(error) if self.config.write_routing_strict => return Err(error),
537 Err(_) => None,
538 },
539 };
540
541 if handle.is_none() && self.config.write_routing_strict {
542 return Err(StorageError::Pool {
543 operation: operation.into(),
544 message: "strict write routing requires a writer-task handle; no handle is \
545 available, so the direct writer fallback was refused"
546 .into(),
547 });
548 }
549 Ok(handle)
550 }
551
552 pub(crate) fn record_direct_route(&self, site: crate::timeout_sink::Site) {
556 if self.write_queue_active() {
557 crate::timeout_sink::emit_direct_route_violation(
558 &crate::timeout_sink::db_label(self),
559 site,
560 );
561 }
562 }
563
564 pub fn writer_task_for_runtime_write(
569 &self,
570 operation: RuntimeWriteOperation,
571 ) -> Result<Option<WriterTaskHandle>, StorageError> {
572 let handle = self.writer_task_for_write(None, operation.operation())?;
573 if handle.is_none() {
574 self.record_direct_route(operation.fallback_site());
575 }
576 Ok(handle)
577 }
578
579 #[cfg(test)]
584 pub(crate) fn writer_task_spawn_count(&self) -> usize {
585 self.writer_task_spawn_count
586 .load(std::sync::atomic::Ordering::SeqCst)
587 }
588
589 pub(crate) fn set_writer_task_join(&self, join: tokio::task::JoinHandle<()>) {
602 let first_store = !self.writer_task_join_stored.swap(true, Ordering::SeqCst);
607 debug_assert!(
608 first_store,
609 "writer task JoinHandle stored twice (even counting a taken one); \
610 the writer_task OnceLock is supposed to make spawn at-most-once per pool"
611 );
612 if first_store {
613 *self.writer_task_join.lock() = Some(join);
614 }
615 }
616
617 pub fn take_writer_task_join(&self) -> Option<tokio::task::JoinHandle<()>> {
635 self.writer_task_join.lock().take()
636 }
637
638 pub(super) fn open_pooled_reader(&self) -> Result<Box<PooledReader>, SqliteError> {
639 let opened_at = Instant::now();
640 Ok(Box::new(PooledReader {
643 conn: self.open_reader_connection()?,
644 opened_at,
645 checkouts: 0,
646 }))
647 }
648
649 pub(super) fn open_reader_connection(&self) -> Result<Connection, SqliteError> {
650 let path = self.read_connection_path()?;
651 #[cfg(any(unix, windows))]
652 if let Some(identity_path) = self.identity_path.as_deref() {
653 self.verify_opened_file_identity(identity_path)?;
654 }
655 let conn = open_reader_connection(path, &self.config)?;
656 #[cfg(any(unix, windows))]
657 if let Some(identity_path) = self.identity_path.as_deref() {
658 self.verify_connection_file_identity(&conn, identity_path)?;
659 }
660 self.verify_opened_database_id(&conn)?;
661 #[cfg(any(test, feature = "test-support"))]
662 crate::statement_observer::install(&conn, &self.statement_observer)?;
663 Ok(conn)
664 }
665
666 fn read_connection_path(&self) -> Result<&Path, SqliteError> {
667 self.read_only_open_target
668 .as_deref()
669 .or(self.identity_path.as_deref())
670 .ok_or_else(|| {
671 SqliteError::InvalidData(
672 "in-memory databases do not support standalone connections".to_string(),
673 )
674 })
675 }
676
677 #[track_caller]
680 pub(super) fn standalone_write_unit(&self) -> Result<StandaloneWriteUnit, SqliteError> {
681 if self.config.read_only {
682 return Err(SqliteError::InvalidData(
683 "database is read-only: standalone write transactions are not permitted".into(),
684 ));
685 }
686 let volume_lease = self.write_admission.acquire()?;
687 let conn = self.open_standalone_connection()?;
688 self.writer_acquisition_counters
689 .standalone_acquisitions
690 .fetch_add(1, Ordering::Relaxed);
691 let unit = StandaloneWriteUnit::new(conn, Arc::clone(&self.write_admission), volume_lease);
692 if !unit.conn().is_autocommit() {
693 return Err(SqliteError::WriterSettlementUnknown);
694 }
695 Ok(unit)
696 }
697
698 pub fn open_standalone_checkpoint(&self) -> Result<StandaloneCheckpoint<'_>, SqliteError> {
701 Ok(StandaloneCheckpoint::new(
702 self,
703 self.open_checkpoint_file()?,
704 ))
705 }
706
707 pub(crate) fn open_checkpoint_file(&self) -> Result<CheckpointFile, SqliteError> {
708 self.open_standalone_connection().map(CheckpointFile::new)
709 }
710
711 pub(crate) fn spawn_writer_task(
712 &self,
713 capacity: usize,
714 ) -> Result<WriterTaskHandle, SqliteError> {
715 let conn = self.open_standalone_connection()?;
716 crate::writer_task::spawn_with_connection(self, conn, capacity)
717 }
718
719 pub(crate) fn open_sql_bridge_writer(
720 self: Arc<Self>,
721 slot: tokio::sync::OwnedSemaphorePermit,
722 ) -> Result<Box<dyn khive_storage::SqlWriter>, StorageError> {
723 let conn = self
724 .open_standalone_connection()
725 .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
726 self.writer_acquisition_counters
727 .standalone_acquisitions
728 .fetch_add(1, Ordering::Relaxed);
729 crate::sql_bridge::build_standalone_writer(self, conn, slot)
730 }
731
732 pub(crate) fn inspect_diagnostic_connection(
733 &self,
734 collect_size_composition: bool,
735 ) -> crate::diagnostics::PoolInspection {
736 crate::diagnostics::inspect_open_connection(
737 self,
738 self.open_standalone_connection(),
739 collect_size_composition,
740 )
741 }
742
743 pub(crate) fn inspect_diagnostic_connection_interruptibly(
744 &self,
745 scope: &crate::read_cancellation::InterruptibleReadScope,
746 collect_size_composition: bool,
747 ) -> Result<crate::diagnostics::PoolInspection, StorageError> {
748 scope.ensure_active()?;
749 crate::diagnostics::inspect_open_connection_interruptibly(
750 self,
751 self.open_standalone_connection(),
752 scope,
753 collect_size_composition,
754 )
755 }
756
757 pub(crate) fn run_fts_maintenance(
760 &self,
761 config: &crate::fts_maintenance::FtsMaintenanceConfig,
762 state: &mut crate::fts_maintenance::FtsMaintenanceState,
763 now: Instant,
764 ) -> Result<Option<crate::fts_maintenance::FtsMaintenanceStep>, String> {
765 if !state.is_due(config, now) {
766 return Ok(None);
767 }
768 let unit = self
769 .standalone_write_unit()
770 .map_err(|error| format!("FTS maintenance admission: {error}"))?;
771 crate::fts_maintenance::run_if_due_with_admission(unit.conn(), config, state, now, || {
772 self.write_admission
773 .check()
774 .map_err(|error| format!("FTS maintenance admission: {error}"))
775 })
776 }
777
778 fn open_standalone_connection(&self) -> Result<Connection, SqliteError> {
781 let path = self.identity_path.as_deref().ok_or_else(|| {
782 SqliteError::InvalidData(
783 "in-memory databases do not support standalone connections".to_string(),
784 )
785 })?;
786
787 if self.config.read_only {
788 return Err(SqliteError::InvalidData(
789 "database is read-only: standalone write connections are not permitted".to_string(),
790 ));
791 }
792
793 #[cfg(any(unix, windows))]
797 self.verify_opened_file_identity(path)?;
798
799 #[cfg(test)]
800 run_identity_open_hook(path, IdentityOpenStage::BeforeStandaloneOpen, None);
801
802 let conn = claimed_file_identity::open_connection(
803 &self.config,
804 path,
805 OpenFlags::SQLITE_OPEN_READ_WRITE
806 | OpenFlags::SQLITE_OPEN_NO_MUTEX
807 | OpenFlags::SQLITE_OPEN_URI,
808 self.identity_path.as_deref(),
809 )?;
810 #[cfg(test)]
811 run_identity_open_hook(path, IdentityOpenStage::AfterStandaloneOpen, Some(&conn));
812 #[cfg(any(unix, windows))]
813 self.verify_connection_file_identity(&conn, path)?;
814 self.verify_opened_database_id(&conn)?;
815 self.configure_standalone_connection(&conn)?;
816 Ok(conn)
817 }
818
819 pub(super) fn configure_standalone_connection(
822 &self,
823 conn: &Connection,
824 ) -> Result<(), SqliteError> {
825 #[cfg(feature = "namespace-trigram-proto")]
826 register_namespace_trigram(conn)?;
827 register_writer_clock(conn)?;
828 register_read_functions(conn)?;
832 conn.busy_timeout(self.config.busy_timeout)?;
833 if self.config.code_map_vfs.is_none() {
834 self.checkpoint_ownership
835 .configure_wal_autocheckpoint(conn)?;
836 }
837 conn.pragma_update(None, "foreign_keys", "ON")?;
838 conn.pragma_update(None, "synchronous", "NORMAL")?;
839
840 let wal_enabled =
841 self.config.wal_mode && current_journal_mode(conn)?.eq_ignore_ascii_case("wal");
842 if wal_enabled {
843 conn.pragma_update(
844 None,
845 "journal_size_limit",
846 self.config.journal_size_limit_bytes,
847 )?;
848 }
849
850 #[cfg(any(test, feature = "test-support"))]
851 crate::statement_observer::install(conn, &self.statement_observer)?;
852 Ok(())
853 }
854
855 #[cfg(any(unix, windows))]
856 pub(super) fn verify_opened_file_identity(&self, path: &Path) -> Result<(), SqliteError> {
857 let Some(expected) = self.opened_file_identity else {
858 return Err(SqliteError::InvalidData(
859 "file-backed pool has no opened database file identity".to_string(),
860 ));
861 };
862 let current = database_file_identity(path).ok();
863 if current != Some(expected) {
864 return Err(SqliteError::InvalidData(
865 "pool database file identity changed since the first open; refusing standalone connection"
866 .to_string(),
867 ));
868 }
869 Ok(())
870 }
871
872 #[cfg(any(unix, windows))]
873 pub(super) fn verify_connection_file_identity(
874 &self,
875 conn: &Connection,
876 path: &Path,
877 ) -> Result<(), SqliteError> {
878 let opened = opened_sqlite_file_identity(conn, path)?;
879 if self.opened_file_identity != Some(opened) {
880 return Err(SqliteError::InvalidData(
881 "pool database file identity changed since the first open; refusing standalone connection"
882 .to_string(),
883 ));
884 }
885 Ok(())
886 }
887
888 fn verify_opened_database_id(&self, conn: &Connection) -> Result<(), SqliteError> {
889 let Some(expected) = self.opened_database_id else {
893 return Ok(());
894 };
895 if self.identity_path.is_some() && read_database_id(conn)? != Some(expected) {
896 return Err(SqliteError::InvalidData(
897 "pool database identity changed since the first open; refusing standalone connection"
898 .to_string(),
899 ));
900 }
901 Ok(())
902 }
903
904 #[cfg(test)]
908 pub(crate) fn effective_wal_autocheckpoint_pages(&self) -> u32 {
909 self.checkpoint_ownership.wal_autocheckpoint_pages()
910 }
911
912 pub fn checkpoint_owner_present(&self) -> bool {
915 self.checkpoint_ownership.state.lock().phase
916 != super::admission::CheckpointOwnership::Unclaimed
917 }
918
919 pub fn timeout_sink_close_handle(&self) -> Option<super::TimeoutSinkCloseHandle> {
923 self.timeout_sink_registration
924 .as_ref()
925 .map(crate::timeout_sink::Registration::close_handle)
926 }
927
928 pub(crate) fn timeout_sink_writer_lease(&self) -> Option<crate::timeout_sink::WriterLease> {
929 self.timeout_sink_registration
930 .as_ref()
931 .map(crate::timeout_sink::Registration::writer_lease)
932 }
933
934 pub fn claim_checkpoint_ownership(&self) -> Result<(), SqliteError> {
956 if !self.checkpoint_ownership.begin_claim() {
957 return Ok(());
958 }
959 let result = (|| {
960 if !self.config.read_only {
961 let writer = self.writer_for_checkpoint_operation()?;
962 writer.conn().pragma_update(None, "wal_autocheckpoint", 0)?;
963 }
964 Ok(())
965 })();
966 self.checkpoint_ownership.finish_claim(result.is_ok());
967 result
968 }
969
970 pub async fn propagate_checkpoint_claim_to_writer_task(&self) -> Result<(), StorageError> {
979 let Some(handle) = self.writer_task_handle()? else {
980 return Ok(());
981 };
982 handle
983 .send_top_level(|conn| {
984 conn.pragma_update(None, "wal_autocheckpoint", 0)
985 .map_err(|e| StorageError::Pool {
986 operation: "claim_checkpoint_ownership".into(),
987 message: e.to_string(),
988 })
989 })
990 .await
991 }
992
993 pub(crate) fn open_standalone_reader(
1002 &self,
1003 purpose: StandaloneReaderPurpose,
1004 ) -> Result<Connection, SqliteError> {
1005 let path = self.read_connection_path()?;
1006
1007 #[cfg(any(unix, windows))]
1008 if let Some(identity_path) = self.identity_path.as_deref() {
1009 self.verify_opened_file_identity(identity_path)?;
1010 }
1011
1012 let conn = claimed_file_identity::open_connection(
1013 &self.config,
1014 path,
1015 OpenFlags::SQLITE_OPEN_READ_ONLY
1016 | OpenFlags::SQLITE_OPEN_NO_MUTEX
1017 | OpenFlags::SQLITE_OPEN_URI,
1018 self.identity_path.as_deref(),
1019 )?;
1020 #[cfg(any(unix, windows))]
1021 if let Some(identity_path) = self.identity_path.as_deref() {
1022 self.verify_connection_file_identity(&conn, identity_path)?;
1023 }
1024 self.verify_opened_database_id(&conn)?;
1025 configure_reader_connection(&conn, &self.config)?;
1026 conn.pragma_update(None, "synchronous", "NORMAL")?;
1027 self.reader_acquisition_counters
1028 .record_standalone_open(purpose);
1029 #[cfg(any(test, feature = "test-support"))]
1030 crate::statement_observer::install(&conn, &self.statement_observer)?;
1031 Ok(conn)
1032 }
1033
1034 pub(super) fn return_reader(&self, conn: Box<PooledReader>, dirty: bool) {
1035 if self.max_readers == 0 {
1036 return;
1037 }
1038
1039 if !conn.past_limit(&self.config, Instant::now())
1040 && reset_reader_connection(&conn.conn, dirty, &self.config)
1041 && reader_connection_is_healthy(&conn.conn)
1042 {
1043 self.enqueue_reader_slot(conn);
1044 return;
1045 }
1046
1047 close_connection_quietly(conn.conn);
1048 self.replace_discarded_reader_slot();
1049 }
1050
1051 fn enqueue_reader_slot(&self, conn: Box<PooledReader>) {
1055 if let Err(conn) = self.readers.push(conn) {
1056 eprintln!("[sqlite-pool] reader pool queue full, discarding replacement connection");
1057 close_connection_quietly(conn.conn);
1058 }
1059 }
1060
1061 pub(super) fn replace_discarded_reader_slot(&self) {
1068 self.reader_acquisition_counters
1069 .reader_discards
1070 .fetch_add(1, Ordering::Relaxed);
1071 match self.open_pooled_reader() {
1072 Ok(conn) => self.enqueue_reader_slot(conn),
1073 Err(error) => {
1074 self.reader_acquisition_counters
1075 .record_reader_replacement_open_failure();
1076 tracing::warn!(target: "khive_db::pool",
1077 %error,
1078 "sqlite-pool: reader replacement connection failed to open; the physical \
1079 pool permanently shrinks by one slot below max_readers"
1080 );
1081 }
1082 }
1083 }
1084}
1085
1086#[cfg(test)]
1087mod checkpoint_presence_tests {
1088 use super::*;
1089
1090 #[test]
1091 fn checkpoint_owner_presence_is_conservative_during_claim() {
1092 let pool = ConnectionPool::new(PoolConfig {
1093 path: None,
1094 ..PoolConfig::default()
1095 })
1096 .unwrap();
1097 assert!(!pool.checkpoint_owner_present());
1098 assert!(pool.checkpoint_ownership.begin_claim());
1099 assert!(pool.checkpoint_owner_present());
1100 pool.checkpoint_ownership.finish_claim(false);
1101 assert!(!pool.checkpoint_owner_present());
1102 pool.claim_checkpoint_ownership().unwrap();
1103 assert!(pool.checkpoint_owner_present());
1104 }
1105}