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 unavailable = |source| StorageError::WriterOwnerUnavailable {
533 operation: operation.into(),
534 source: Box::new(source),
535 };
536 let handle = match cached {
537 Some(handle) => Some(handle.clone()),
538 None => match self.writer_task_handle() {
539 Ok(handle) => handle,
540 Err(error) if self.config.write_routing_strict => return Err(unavailable(error)),
541 Err(_) => None,
542 },
543 };
544 if self.config.write_routing_strict
545 && handle.as_ref().is_none_or(WriterTaskHandle::is_closed)
546 {
547 return Err(unavailable(StorageError::Pool {
548 operation: operation.into(),
549 message: "strict write routing requires a live writer owner".into(),
550 }));
551 }
552 Ok(handle)
553 }
554
555 pub(crate) fn record_direct_route(&self, site: crate::timeout_sink::Site) {
559 if self.write_queue_active() {
560 crate::timeout_sink::emit_direct_route_violation(
561 &crate::timeout_sink::db_label(self),
562 site,
563 );
564 }
565 }
566
567 pub fn writer_task_for_runtime_write(
572 &self,
573 operation: RuntimeWriteOperation,
574 ) -> Result<Option<WriterTaskHandle>, StorageError> {
575 let handle = self.writer_task_for_write(None, operation.operation())?;
576 if handle.is_none() {
577 self.record_direct_route(operation.fallback_site());
578 }
579 Ok(handle)
580 }
581
582 #[cfg(test)]
587 pub(crate) fn writer_task_spawn_count(&self) -> usize {
588 self.writer_task_spawn_count
589 .load(std::sync::atomic::Ordering::SeqCst)
590 }
591
592 pub(crate) fn set_writer_task_join(&self, join: tokio::task::JoinHandle<()>) {
605 let first_store = !self.writer_task_join_stored.swap(true, Ordering::SeqCst);
610 debug_assert!(
611 first_store,
612 "writer task JoinHandle stored twice (even counting a taken one); \
613 the writer_task OnceLock is supposed to make spawn at-most-once per pool"
614 );
615 if first_store {
616 *self.writer_task_join.lock() = Some(join);
617 }
618 }
619
620 pub fn take_writer_task_join(&self) -> Option<tokio::task::JoinHandle<()>> {
638 self.writer_task_join.lock().take()
639 }
640
641 pub(super) fn open_pooled_reader(&self) -> Result<Box<PooledReader>, SqliteError> {
642 let opened_at = Instant::now();
643 Ok(Box::new(PooledReader {
646 conn: crate::ProgressConn::new(self.open_reader_connection()?)?,
647 opened_at,
648 checkouts: 0,
649 }))
650 }
651
652 pub(super) fn open_reader_connection(&self) -> Result<Connection, SqliteError> {
653 let path = self.read_connection_path()?;
654 #[cfg(any(unix, windows))]
655 if let Some(identity_path) = self.identity_path.as_deref() {
656 self.verify_opened_file_identity(identity_path)?;
657 }
658 let conn = open_reader_connection(path, &self.config)?;
659 #[cfg(any(unix, windows))]
660 if let Some(identity_path) = self.identity_path.as_deref() {
661 self.verify_connection_file_identity(&conn, identity_path)?;
662 }
663 self.verify_opened_database_id(&conn)?;
664 #[cfg(any(test, feature = "test-support"))]
665 crate::statement_observer::install(&conn, &self.statement_observer)?;
666 Ok(conn)
667 }
668
669 fn read_connection_path(&self) -> Result<&Path, SqliteError> {
670 self.read_only_open_target
671 .as_deref()
672 .or(self.identity_path.as_deref())
673 .ok_or_else(|| {
674 SqliteError::InvalidData(
675 "in-memory databases do not support standalone connections".to_string(),
676 )
677 })
678 }
679
680 #[track_caller]
683 pub(super) fn standalone_write_unit(&self) -> Result<StandaloneWriteUnit, SqliteError> {
684 self.ensure_request_write_route("standalone_write")?;
685 if self.config.read_only {
686 return Err(SqliteError::InvalidData(
687 "database is read-only: standalone write transactions are not permitted".into(),
688 ));
689 }
690 let volume_lease = self
691 .write_admission
692 .acquire(crate::disk_guard::LeaseClass::Standalone)?;
693 let conn = self.open_standalone_connection()?;
694 self.writer_acquisition_counters
695 .standalone_acquisitions
696 .fetch_add(1, Ordering::Relaxed);
697 let unit = StandaloneWriteUnit::new(conn, Arc::clone(&self.write_admission), volume_lease);
698 if !unit.conn().is_autocommit() {
699 return Err(SqliteError::WriterSettlementUnknown);
700 }
701 Ok(unit)
702 }
703
704 pub fn open_standalone_checkpoint(&self) -> Result<StandaloneCheckpoint<'_>, SqliteError> {
707 Ok(StandaloneCheckpoint::new(
708 self,
709 self.open_checkpoint_file()?,
710 ))
711 }
712
713 pub(crate) fn open_checkpoint_file(&self) -> Result<CheckpointFile, SqliteError> {
714 self.open_standalone_connection().map(CheckpointFile::new)
715 }
716
717 pub(crate) fn spawn_writer_task(
718 &self,
719 capacity: usize,
720 ) -> Result<WriterTaskHandle, SqliteError> {
721 let conn = self.open_standalone_connection()?;
722 crate::writer_task::spawn_with_connection(self, conn, capacity)
723 }
724
725 pub(crate) fn open_sql_bridge_writer(
726 self: Arc<Self>,
727 slot: tokio::sync::OwnedSemaphorePermit,
728 ) -> Result<Box<dyn khive_storage::SqlWriter>, StorageError> {
729 self.ensure_request_write_route("sql_bridge_writer")
730 .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
731 let conn = self
732 .open_standalone_connection()
733 .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
734 self.writer_acquisition_counters
735 .standalone_acquisitions
736 .fetch_add(1, Ordering::Relaxed);
737 crate::sql_bridge::build_standalone_writer(self, conn, slot)
738 }
739
740 pub(crate) fn inspect_diagnostic_connection(
741 &self,
742 collect_size_composition: bool,
743 ) -> crate::diagnostics::PoolInspection {
744 crate::diagnostics::inspect_open_connection(
745 self,
746 self.open_standalone_connection(),
747 collect_size_composition,
748 )
749 }
750
751 pub(crate) fn inspect_diagnostic_connection_interruptibly(
752 &self,
753 scope: &crate::read_cancellation::InterruptibleReadScope,
754 collect_size_composition: bool,
755 ) -> Result<crate::diagnostics::PoolInspection, StorageError> {
756 scope.ensure_active()?;
757 crate::diagnostics::inspect_open_connection_interruptibly(
758 self,
759 self.open_standalone_connection(),
760 scope,
761 collect_size_composition,
762 )
763 }
764
765 pub(crate) fn run_fts_maintenance(
768 &self,
769 config: &crate::fts_maintenance::FtsMaintenanceConfig,
770 state: &mut crate::fts_maintenance::FtsMaintenanceState,
771 now: Instant,
772 ) -> Result<Option<crate::fts_maintenance::FtsMaintenanceStep>, String> {
773 if !state.is_due(config, now) {
774 return Ok(None);
775 }
776 let unit = {
777 let _class =
778 crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Maintenance);
779 self.standalone_write_unit()
780 }
781 .map_err(|error| format!("FTS maintenance admission: {error}"))?;
782 crate::fts_maintenance::run_if_due_with_admission(unit.conn(), config, state, now, || {
783 self.write_admission
784 .check()
785 .map_err(|error| format!("FTS maintenance admission: {error}"))
786 })
787 }
788
789 fn open_standalone_connection(&self) -> Result<Connection, SqliteError> {
792 let path = self.identity_path.as_deref().ok_or_else(|| {
793 SqliteError::InvalidData(
794 "in-memory databases do not support standalone connections".to_string(),
795 )
796 })?;
797
798 if self.config.read_only {
799 return Err(SqliteError::InvalidData(
800 "database is read-only: standalone write connections are not permitted".to_string(),
801 ));
802 }
803
804 #[cfg(any(unix, windows))]
808 self.verify_opened_file_identity(path)?;
809
810 #[cfg(test)]
811 run_identity_open_hook(path, IdentityOpenStage::BeforeStandaloneOpen, None);
812
813 let conn = claimed_file_identity::open_connection(
814 &self.config,
815 path,
816 OpenFlags::SQLITE_OPEN_READ_WRITE
817 | OpenFlags::SQLITE_OPEN_NO_MUTEX
818 | OpenFlags::SQLITE_OPEN_URI,
819 self.identity_path.as_deref(),
820 )?;
821 #[cfg(test)]
822 run_identity_open_hook(path, IdentityOpenStage::AfterStandaloneOpen, Some(&conn));
823 #[cfg(any(unix, windows))]
824 self.verify_connection_file_identity(&conn, path)?;
825 self.verify_opened_database_id(&conn)?;
826 self.configure_standalone_connection(&conn)?;
827 Ok(conn)
828 }
829
830 pub(super) fn configure_standalone_connection(
833 &self,
834 conn: &Connection,
835 ) -> Result<(), SqliteError> {
836 #[cfg(feature = "namespace-trigram-proto")]
837 register_namespace_trigram(conn)?;
838 register_writer_clock(conn)?;
839 register_read_functions(conn)?;
843 conn.busy_timeout(self.config.busy_timeout)?;
844 if self.config.code_map_vfs.is_none() {
845 self.checkpoint_ownership
846 .configure_wal_autocheckpoint(conn)?;
847 }
848 conn.pragma_update(None, "foreign_keys", "ON")?;
849 conn.pragma_update(None, "synchronous", "NORMAL")?;
850
851 let wal_enabled =
852 self.config.wal_mode && current_journal_mode(conn)?.eq_ignore_ascii_case("wal");
853 if wal_enabled {
854 conn.pragma_update(
855 None,
856 "journal_size_limit",
857 self.config.journal_size_limit_bytes,
858 )?;
859 }
860
861 #[cfg(any(test, feature = "test-support"))]
862 crate::statement_observer::install(conn, &self.statement_observer)?;
863 Ok(())
864 }
865
866 #[cfg(any(unix, windows))]
867 pub(super) fn verify_opened_file_identity(&self, path: &Path) -> Result<(), SqliteError> {
868 let Some(expected) = self.opened_file_identity else {
869 return Err(SqliteError::InvalidData(
870 "file-backed pool has no opened database file identity".to_string(),
871 ));
872 };
873 let current = database_file_identity(path).ok();
874 if current != Some(expected) {
875 return Err(SqliteError::InvalidData(
876 "pool database file identity changed since the first open; refusing standalone connection"
877 .to_string(),
878 ));
879 }
880 Ok(())
881 }
882
883 #[cfg(any(unix, windows))]
884 pub(super) fn verify_connection_file_identity(
885 &self,
886 conn: &Connection,
887 path: &Path,
888 ) -> Result<(), SqliteError> {
889 let opened = opened_sqlite_file_identity(conn, path)?;
890 if self.opened_file_identity != Some(opened) {
891 return Err(SqliteError::InvalidData(
892 "pool database file identity changed since the first open; refusing standalone connection"
893 .to_string(),
894 ));
895 }
896 Ok(())
897 }
898
899 fn verify_opened_database_id(&self, conn: &Connection) -> Result<(), SqliteError> {
900 let Some(expected) = self.opened_database_id else {
904 return Ok(());
905 };
906 if self.identity_path.is_some() && read_database_id(conn)? != Some(expected) {
907 return Err(SqliteError::InvalidData(
908 "pool database identity changed since the first open; refusing standalone connection"
909 .to_string(),
910 ));
911 }
912 Ok(())
913 }
914
915 #[cfg(test)]
919 pub(crate) fn effective_wal_autocheckpoint_pages(&self) -> u32 {
920 self.checkpoint_ownership.wal_autocheckpoint_pages()
921 }
922
923 pub fn checkpoint_owner_present(&self) -> bool {
926 self.checkpoint_ownership.state.lock().phase
927 != super::admission::CheckpointOwnership::Unclaimed
928 }
929
930 pub fn timeout_sink_close_handle(&self) -> Option<super::TimeoutSinkCloseHandle> {
934 self.timeout_sink_registration
935 .as_ref()
936 .map(crate::timeout_sink::Registration::close_handle)
937 }
938
939 pub(crate) fn timeout_sink_writer_lease(&self) -> Option<crate::timeout_sink::WriterLease> {
940 self.timeout_sink_registration
941 .as_ref()
942 .map(crate::timeout_sink::Registration::writer_lease)
943 }
944
945 pub fn claim_checkpoint_ownership(&self) -> Result<(), SqliteError> {
967 if !self.checkpoint_ownership.begin_claim() {
968 return Ok(());
969 }
970 let result = (|| {
971 if !self.config.read_only {
972 let writer = self.writer_for_checkpoint_operation()?;
973 writer.conn().pragma_update(None, "wal_autocheckpoint", 0)?;
974 }
975 Ok(())
976 })();
977 self.checkpoint_ownership.finish_claim(result.is_ok());
978 result
979 }
980
981 pub async fn propagate_checkpoint_claim_to_writer_task(&self) -> Result<(), StorageError> {
990 let Some(handle) = self.writer_task_handle()? else {
991 return Ok(());
992 };
993 handle
994 .send_top_level(|conn| {
995 conn.pragma_update(None, "wal_autocheckpoint", 0)
996 .map_err(|e| StorageError::Pool {
997 operation: "claim_checkpoint_ownership".into(),
998 message: e.to_string(),
999 })
1000 })
1001 .await
1002 }
1003
1004 pub(crate) fn open_standalone_reader(
1013 &self,
1014 purpose: StandaloneReaderPurpose,
1015 ) -> Result<Connection, SqliteError> {
1016 let path = self.read_connection_path()?;
1017
1018 #[cfg(any(unix, windows))]
1019 if let Some(identity_path) = self.identity_path.as_deref() {
1020 self.verify_opened_file_identity(identity_path)?;
1021 }
1022
1023 let conn = claimed_file_identity::open_connection(
1024 &self.config,
1025 path,
1026 OpenFlags::SQLITE_OPEN_READ_ONLY
1027 | OpenFlags::SQLITE_OPEN_NO_MUTEX
1028 | OpenFlags::SQLITE_OPEN_URI,
1029 self.identity_path.as_deref(),
1030 )?;
1031 #[cfg(any(unix, windows))]
1032 if let Some(identity_path) = self.identity_path.as_deref() {
1033 self.verify_connection_file_identity(&conn, identity_path)?;
1034 }
1035 self.verify_opened_database_id(&conn)?;
1036 configure_reader_connection(&conn, &self.config)?;
1037 conn.pragma_update(None, "synchronous", "NORMAL")?;
1038 self.reader_acquisition_counters
1039 .record_standalone_open(purpose);
1040 #[cfg(any(test, feature = "test-support"))]
1041 crate::statement_observer::install(&conn, &self.statement_observer)?;
1042 Ok(conn)
1043 }
1044
1045 pub(super) fn return_reader(&self, conn: Box<PooledReader>, dirty: bool) {
1046 if self.max_readers == 0 {
1047 return;
1048 }
1049
1050 if !conn.past_limit(&self.config, Instant::now())
1051 && reset_reader_connection(&conn.conn, dirty, &self.config)
1052 && reader_connection_is_healthy(&conn.conn)
1053 {
1054 self.enqueue_reader_slot(conn);
1055 return;
1056 }
1057
1058 close_connection_quietly(conn.conn.into_inner());
1059 self.replace_discarded_reader_slot();
1060 }
1061
1062 fn enqueue_reader_slot(&self, conn: Box<PooledReader>) {
1066 if let Err(conn) = self.readers.push(conn) {
1067 eprintln!("[sqlite-pool] reader pool queue full, discarding replacement connection");
1068 close_connection_quietly(conn.conn.into_inner());
1069 }
1070 }
1071
1072 pub(super) fn replace_discarded_reader_slot(&self) {
1079 self.reader_acquisition_counters
1080 .reader_discards
1081 .fetch_add(1, Ordering::Relaxed);
1082 match self.open_pooled_reader() {
1083 Ok(conn) => self.enqueue_reader_slot(conn),
1084 Err(error) => {
1085 self.reader_acquisition_counters
1086 .record_reader_replacement_open_failure();
1087 tracing::warn!(target: "khive_db::pool",
1088 %error,
1089 "sqlite-pool: reader replacement connection failed to open; the physical \
1090 pool permanently shrinks by one slot below max_readers"
1091 );
1092 }
1093 }
1094 }
1095}
1096
1097#[cfg(test)]
1098mod checkpoint_presence_tests {
1099 use super::*;
1100
1101 #[test]
1102 fn checkpoint_owner_presence_is_conservative_during_claim() {
1103 let pool = ConnectionPool::new(PoolConfig {
1104 path: None,
1105 ..PoolConfig::default()
1106 })
1107 .unwrap();
1108 assert!(!pool.checkpoint_owner_present());
1109 assert!(pool.checkpoint_ownership.begin_claim());
1110 assert!(pool.checkpoint_owner_present());
1111 pool.checkpoint_ownership.finish_claim(false);
1112 assert!(!pool.checkpoint_owner_present());
1113 pool.claim_checkpoint_ownership().unwrap();
1114 assert!(pool.checkpoint_owner_present());
1115 }
1116}