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: crate::ProgressConn::new(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
687 .write_admission
688 .acquire(crate::disk_guard::LeaseClass::Standalone)?;
689 let conn = self.open_standalone_connection()?;
690 self.writer_acquisition_counters
691 .standalone_acquisitions
692 .fetch_add(1, Ordering::Relaxed);
693 let unit = StandaloneWriteUnit::new(conn, Arc::clone(&self.write_admission), volume_lease);
694 if !unit.conn().is_autocommit() {
695 return Err(SqliteError::WriterSettlementUnknown);
696 }
697 Ok(unit)
698 }
699
700 pub fn open_standalone_checkpoint(&self) -> Result<StandaloneCheckpoint<'_>, SqliteError> {
703 Ok(StandaloneCheckpoint::new(
704 self,
705 self.open_checkpoint_file()?,
706 ))
707 }
708
709 pub(crate) fn open_checkpoint_file(&self) -> Result<CheckpointFile, SqliteError> {
710 self.open_standalone_connection().map(CheckpointFile::new)
711 }
712
713 pub(crate) fn spawn_writer_task(
714 &self,
715 capacity: usize,
716 ) -> Result<WriterTaskHandle, SqliteError> {
717 let conn = self.open_standalone_connection()?;
718 crate::writer_task::spawn_with_connection(self, conn, capacity)
719 }
720
721 pub(crate) fn open_sql_bridge_writer(
722 self: Arc<Self>,
723 slot: tokio::sync::OwnedSemaphorePermit,
724 ) -> Result<Box<dyn khive_storage::SqlWriter>, StorageError> {
725 let conn = self
726 .open_standalone_connection()
727 .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
728 self.writer_acquisition_counters
729 .standalone_acquisitions
730 .fetch_add(1, Ordering::Relaxed);
731 crate::sql_bridge::build_standalone_writer(self, conn, slot)
732 }
733
734 pub(crate) fn inspect_diagnostic_connection(
735 &self,
736 collect_size_composition: bool,
737 ) -> crate::diagnostics::PoolInspection {
738 crate::diagnostics::inspect_open_connection(
739 self,
740 self.open_standalone_connection(),
741 collect_size_composition,
742 )
743 }
744
745 pub(crate) fn inspect_diagnostic_connection_interruptibly(
746 &self,
747 scope: &crate::read_cancellation::InterruptibleReadScope,
748 collect_size_composition: bool,
749 ) -> Result<crate::diagnostics::PoolInspection, StorageError> {
750 scope.ensure_active()?;
751 crate::diagnostics::inspect_open_connection_interruptibly(
752 self,
753 self.open_standalone_connection(),
754 scope,
755 collect_size_composition,
756 )
757 }
758
759 pub(crate) fn run_fts_maintenance(
762 &self,
763 config: &crate::fts_maintenance::FtsMaintenanceConfig,
764 state: &mut crate::fts_maintenance::FtsMaintenanceState,
765 now: Instant,
766 ) -> Result<Option<crate::fts_maintenance::FtsMaintenanceStep>, String> {
767 if !state.is_due(config, now) {
768 return Ok(None);
769 }
770 let unit = {
771 let _class =
772 crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Maintenance);
773 self.standalone_write_unit()
774 }
775 .map_err(|error| format!("FTS maintenance admission: {error}"))?;
776 crate::fts_maintenance::run_if_due_with_admission(unit.conn(), config, state, now, || {
777 self.write_admission
778 .check()
779 .map_err(|error| format!("FTS maintenance admission: {error}"))
780 })
781 }
782
783 fn open_standalone_connection(&self) -> Result<Connection, SqliteError> {
786 let path = self.identity_path.as_deref().ok_or_else(|| {
787 SqliteError::InvalidData(
788 "in-memory databases do not support standalone connections".to_string(),
789 )
790 })?;
791
792 if self.config.read_only {
793 return Err(SqliteError::InvalidData(
794 "database is read-only: standalone write connections are not permitted".to_string(),
795 ));
796 }
797
798 #[cfg(any(unix, windows))]
802 self.verify_opened_file_identity(path)?;
803
804 #[cfg(test)]
805 run_identity_open_hook(path, IdentityOpenStage::BeforeStandaloneOpen, None);
806
807 let conn = claimed_file_identity::open_connection(
808 &self.config,
809 path,
810 OpenFlags::SQLITE_OPEN_READ_WRITE
811 | OpenFlags::SQLITE_OPEN_NO_MUTEX
812 | OpenFlags::SQLITE_OPEN_URI,
813 self.identity_path.as_deref(),
814 )?;
815 #[cfg(test)]
816 run_identity_open_hook(path, IdentityOpenStage::AfterStandaloneOpen, Some(&conn));
817 #[cfg(any(unix, windows))]
818 self.verify_connection_file_identity(&conn, path)?;
819 self.verify_opened_database_id(&conn)?;
820 self.configure_standalone_connection(&conn)?;
821 Ok(conn)
822 }
823
824 pub(super) fn configure_standalone_connection(
827 &self,
828 conn: &Connection,
829 ) -> Result<(), SqliteError> {
830 #[cfg(feature = "namespace-trigram-proto")]
831 register_namespace_trigram(conn)?;
832 register_writer_clock(conn)?;
833 register_read_functions(conn)?;
837 conn.busy_timeout(self.config.busy_timeout)?;
838 if self.config.code_map_vfs.is_none() {
839 self.checkpoint_ownership
840 .configure_wal_autocheckpoint(conn)?;
841 }
842 conn.pragma_update(None, "foreign_keys", "ON")?;
843 conn.pragma_update(None, "synchronous", "NORMAL")?;
844
845 let wal_enabled =
846 self.config.wal_mode && current_journal_mode(conn)?.eq_ignore_ascii_case("wal");
847 if wal_enabled {
848 conn.pragma_update(
849 None,
850 "journal_size_limit",
851 self.config.journal_size_limit_bytes,
852 )?;
853 }
854
855 #[cfg(any(test, feature = "test-support"))]
856 crate::statement_observer::install(conn, &self.statement_observer)?;
857 Ok(())
858 }
859
860 #[cfg(any(unix, windows))]
861 pub(super) fn verify_opened_file_identity(&self, path: &Path) -> Result<(), SqliteError> {
862 let Some(expected) = self.opened_file_identity else {
863 return Err(SqliteError::InvalidData(
864 "file-backed pool has no opened database file identity".to_string(),
865 ));
866 };
867 let current = database_file_identity(path).ok();
868 if current != Some(expected) {
869 return Err(SqliteError::InvalidData(
870 "pool database file identity changed since the first open; refusing standalone connection"
871 .to_string(),
872 ));
873 }
874 Ok(())
875 }
876
877 #[cfg(any(unix, windows))]
878 pub(super) fn verify_connection_file_identity(
879 &self,
880 conn: &Connection,
881 path: &Path,
882 ) -> Result<(), SqliteError> {
883 let opened = opened_sqlite_file_identity(conn, path)?;
884 if self.opened_file_identity != Some(opened) {
885 return Err(SqliteError::InvalidData(
886 "pool database file identity changed since the first open; refusing standalone connection"
887 .to_string(),
888 ));
889 }
890 Ok(())
891 }
892
893 fn verify_opened_database_id(&self, conn: &Connection) -> Result<(), SqliteError> {
894 let Some(expected) = self.opened_database_id else {
898 return Ok(());
899 };
900 if self.identity_path.is_some() && read_database_id(conn)? != Some(expected) {
901 return Err(SqliteError::InvalidData(
902 "pool database identity changed since the first open; refusing standalone connection"
903 .to_string(),
904 ));
905 }
906 Ok(())
907 }
908
909 #[cfg(test)]
913 pub(crate) fn effective_wal_autocheckpoint_pages(&self) -> u32 {
914 self.checkpoint_ownership.wal_autocheckpoint_pages()
915 }
916
917 pub fn checkpoint_owner_present(&self) -> bool {
920 self.checkpoint_ownership.state.lock().phase
921 != super::admission::CheckpointOwnership::Unclaimed
922 }
923
924 pub fn timeout_sink_close_handle(&self) -> Option<super::TimeoutSinkCloseHandle> {
928 self.timeout_sink_registration
929 .as_ref()
930 .map(crate::timeout_sink::Registration::close_handle)
931 }
932
933 pub(crate) fn timeout_sink_writer_lease(&self) -> Option<crate::timeout_sink::WriterLease> {
934 self.timeout_sink_registration
935 .as_ref()
936 .map(crate::timeout_sink::Registration::writer_lease)
937 }
938
939 pub fn claim_checkpoint_ownership(&self) -> Result<(), SqliteError> {
961 if !self.checkpoint_ownership.begin_claim() {
962 return Ok(());
963 }
964 let result = (|| {
965 if !self.config.read_only {
966 let writer = self.writer_for_checkpoint_operation()?;
967 writer.conn().pragma_update(None, "wal_autocheckpoint", 0)?;
968 }
969 Ok(())
970 })();
971 self.checkpoint_ownership.finish_claim(result.is_ok());
972 result
973 }
974
975 pub async fn propagate_checkpoint_claim_to_writer_task(&self) -> Result<(), StorageError> {
984 let Some(handle) = self.writer_task_handle()? else {
985 return Ok(());
986 };
987 handle
988 .send_top_level(|conn| {
989 conn.pragma_update(None, "wal_autocheckpoint", 0)
990 .map_err(|e| StorageError::Pool {
991 operation: "claim_checkpoint_ownership".into(),
992 message: e.to_string(),
993 })
994 })
995 .await
996 }
997
998 pub(crate) fn open_standalone_reader(
1007 &self,
1008 purpose: StandaloneReaderPurpose,
1009 ) -> Result<Connection, SqliteError> {
1010 let path = self.read_connection_path()?;
1011
1012 #[cfg(any(unix, windows))]
1013 if let Some(identity_path) = self.identity_path.as_deref() {
1014 self.verify_opened_file_identity(identity_path)?;
1015 }
1016
1017 let conn = claimed_file_identity::open_connection(
1018 &self.config,
1019 path,
1020 OpenFlags::SQLITE_OPEN_READ_ONLY
1021 | OpenFlags::SQLITE_OPEN_NO_MUTEX
1022 | OpenFlags::SQLITE_OPEN_URI,
1023 self.identity_path.as_deref(),
1024 )?;
1025 #[cfg(any(unix, windows))]
1026 if let Some(identity_path) = self.identity_path.as_deref() {
1027 self.verify_connection_file_identity(&conn, identity_path)?;
1028 }
1029 self.verify_opened_database_id(&conn)?;
1030 configure_reader_connection(&conn, &self.config)?;
1031 conn.pragma_update(None, "synchronous", "NORMAL")?;
1032 self.reader_acquisition_counters
1033 .record_standalone_open(purpose);
1034 #[cfg(any(test, feature = "test-support"))]
1035 crate::statement_observer::install(&conn, &self.statement_observer)?;
1036 Ok(conn)
1037 }
1038
1039 pub(super) fn return_reader(&self, conn: Box<PooledReader>, dirty: bool) {
1040 if self.max_readers == 0 {
1041 return;
1042 }
1043
1044 if !conn.past_limit(&self.config, Instant::now())
1045 && reset_reader_connection(&conn.conn, dirty, &self.config)
1046 && reader_connection_is_healthy(&conn.conn)
1047 {
1048 self.enqueue_reader_slot(conn);
1049 return;
1050 }
1051
1052 close_connection_quietly(conn.conn.into_inner());
1053 self.replace_discarded_reader_slot();
1054 }
1055
1056 fn enqueue_reader_slot(&self, conn: Box<PooledReader>) {
1060 if let Err(conn) = self.readers.push(conn) {
1061 eprintln!("[sqlite-pool] reader pool queue full, discarding replacement connection");
1062 close_connection_quietly(conn.conn.into_inner());
1063 }
1064 }
1065
1066 pub(super) fn replace_discarded_reader_slot(&self) {
1073 self.reader_acquisition_counters
1074 .reader_discards
1075 .fetch_add(1, Ordering::Relaxed);
1076 match self.open_pooled_reader() {
1077 Ok(conn) => self.enqueue_reader_slot(conn),
1078 Err(error) => {
1079 self.reader_acquisition_counters
1080 .record_reader_replacement_open_failure();
1081 tracing::warn!(target: "khive_db::pool",
1082 %error,
1083 "sqlite-pool: reader replacement connection failed to open; the physical \
1084 pool permanently shrinks by one slot below max_readers"
1085 );
1086 }
1087 }
1088 }
1089}
1090
1091#[cfg(test)]
1092mod checkpoint_presence_tests {
1093 use super::*;
1094
1095 #[test]
1096 fn checkpoint_owner_presence_is_conservative_during_claim() {
1097 let pool = ConnectionPool::new(PoolConfig {
1098 path: None,
1099 ..PoolConfig::default()
1100 })
1101 .unwrap();
1102 assert!(!pool.checkpoint_owner_present());
1103 assert!(pool.checkpoint_ownership.begin_claim());
1104 assert!(pool.checkpoint_owner_present());
1105 pool.checkpoint_ownership.finish_claim(false);
1106 assert!(!pool.checkpoint_owner_present());
1107 pool.claim_checkpoint_ownership().unwrap();
1108 assert!(pool.checkpoint_owner_present());
1109 }
1110}