1use super::*;
2
3#[cfg(test)]
4pub(super) type SpaceProbe = dyn Fn(&Path) -> std::io::Result<u64> + Send + Sync;
5
6#[cfg(test)]
7thread_local! {
8 pub(super) static STARTUP_SPACE_PROBE: std::cell::RefCell<Option<(u64, Arc<SpaceProbe>)>> =
9 const { std::cell::RefCell::new(None) };
10}
11
12pub(crate) struct WriteAdmission {
17 database_path: Option<PathBuf>,
18 volume: Option<PathBuf>,
19 expected_volume: Option<VolumeIdentity>,
20 volume_lock_dir: Option<PathBuf>,
21 floor_bytes: u64,
22 guard_deadline: Duration,
23 settlement_unknown: AtomicBool,
26 lease_timeouts: AtomicU64,
29 #[cfg(test)]
30 space_probe: Mutex<Option<Arc<SpaceProbe>>>,
31 #[cfg(test)]
32 current_volume_override: Mutex<Option<VolumeIdentity>>,
33}
34
35impl WriteAdmission {
36 pub(crate) fn new(
37 database_path: Option<PathBuf>,
38 floor_bytes: u64,
39 guard_deadline_ms: u64,
40 volume_lock_dir: Option<PathBuf>,
41 ) -> Result<Self, SqliteError> {
42 let volume = database_path.clone();
43 let expected_volume = volume.as_deref().map(VolumeIdentity::resolve).transpose()?;
44 #[cfg(test)]
45 let (floor_bytes, space_probe) = STARTUP_SPACE_PROBE.with(|probe| {
46 probe
47 .borrow()
48 .as_ref()
49 .map(|(floor, probe)| (*floor, Some(Arc::clone(probe))))
50 .unwrap_or((floor_bytes, None))
51 });
52 Ok(Self {
53 database_path,
54 volume,
55 expected_volume,
56 volume_lock_dir,
57 floor_bytes,
58 guard_deadline: Duration::from_millis(guard_deadline_ms),
59 settlement_unknown: AtomicBool::new(false),
60 lease_timeouts: AtomicU64::new(0),
61 #[cfg(test)]
62 space_probe: Mutex::new(space_probe),
63 #[cfg(test)]
64 current_volume_override: Mutex::new(None),
65 })
66 }
67
68 pub(crate) fn for_canonical_path(database_path: Option<PathBuf>) -> Result<Self, SqliteError> {
71 if database_path.is_none() {
72 return Self::new(None, 0, DEFAULT_DISK_GUARD_DEADLINE_MS, None);
73 }
74 let policy = crate::migrations::MigrationWritePolicy::from_environment()?;
75 Self::for_migration_policy(database_path, &policy)
76 }
77
78 pub(crate) fn for_migration_policy(
79 database_path: Option<PathBuf>,
80 policy: &crate::migrations::MigrationWritePolicy,
81 ) -> Result<Self, SqliteError> {
82 let effective = policy.disk_guard_config();
83 if effective.legacy_environment_present {
84 tracing::warn!(
85 "legacy SQLite reserve setting is deprecated; use KHIVE_SQLITE_DISK_RESERVE_BYTES"
86 );
87 }
88 if effective.reserve_bytes == 0 {
89 tracing::warn!("SQLite disk reserve is zero; logical writes have no floor refusal");
90 }
91 Self::new(
92 database_path,
93 effective.reserve_bytes,
94 effective.guard_deadline_ms,
95 Some(policy.volume_lock_dir().to_path_buf()),
96 )
97 }
98
99 pub(super) fn verify_current_volume(&self) -> Result<(), SqliteError> {
100 let (Some(path), Some(expected)) = (self.volume.as_deref(), self.expected_volume.as_ref())
101 else {
102 return Ok(());
103 };
104 #[cfg(test)]
105 let current = self.current_volume_override.lock().clone();
106 #[cfg(not(test))]
107 let current: Option<VolumeIdentity> = None;
108 let unchanged = match current {
109 Some(identity) => &identity == expected,
110 None => expected.still_identifies(path)?,
111 };
112 if !unchanged {
113 return Err(SqliteError::CapacityUnavailable {
114 phase: CapacityUnavailablePhase::Identity,
115 message: "database volume changed after admission identity was captured"
116 .to_string(),
117 });
118 }
119 Ok(())
120 }
121
122 pub(crate) fn close_retired_connection(&self, conn: Connection) -> Result<(), SqliteError> {
128 let database_path = self
129 .database_path
130 .as_ref()
131 .map(|path| path.display().to_string())
132 .unwrap_or_else(|| ":memory:".to_string());
133 let volume_key = self
134 .expected_volume
135 .as_ref()
136 .map(VolumeIdentity::diagnostic_key)
137 .unwrap_or_else(|| "in-memory".to_string());
138 let settled = crate::connection_settlement::close_retired_connection(
139 conn,
140 &database_path,
141 &volume_key,
142 );
143 if settled.is_err() {
144 self.settlement_unknown.store(true, Ordering::Release);
145 }
146 settled
147 }
148
149 pub(crate) fn ensure_settled(&self) -> Result<(), SqliteError> {
150 if self.settlement_unknown.load(Ordering::Acquire) {
151 return Err(SqliteError::WriterPoisoned);
152 }
153 Ok(())
154 }
155
156 pub(crate) fn volume_identity(&self) -> Result<Option<VolumeIdentity>, SqliteError> {
157 self.verify_current_volume()?;
158 Ok(self.expected_volume.clone())
159 }
160
161 fn available_space(&self, volume: &Path) -> std::io::Result<u64> {
162 #[cfg(test)]
163 if let Some(probe) = self.space_probe.lock().as_ref() {
164 return probe(volume);
165 }
166 fs4::available_space(volume)
167 }
168
169 pub(crate) fn check(&self) -> Result<(), SqliteError> {
170 self.check_with_headroom(0)
171 }
172
173 pub(crate) fn check_with_headroom(
174 &self,
175 required_headroom_bytes: u64,
176 ) -> Result<(), SqliteError> {
177 let Some(volume) = self.volume.as_deref() else {
178 return Ok(());
179 };
180 self.verify_current_volume()?;
181 let identity =
182 self.expected_volume
183 .as_ref()
184 .ok_or_else(|| SqliteError::CapacityUnavailable {
185 phase: CapacityUnavailablePhase::Identity,
186 message: "file-backed admission has no captured volume identity".to_string(),
187 })?;
188 let available = self
189 .available_space(identity.probe_path())
190 .map_err(|error| SqliteError::CapacityUnavailable {
191 phase: CapacityUnavailablePhase::Probe,
192 message: format!(
193 "cannot sample available space on {}: {error}",
194 volume.display()
195 ),
196 })?;
197 self.verify_current_volume()?;
198 let threshold = self.floor_bytes.checked_add(required_headroom_bytes);
204 if threshold.is_none()
205 || (threshold != Some(0) && available <= threshold.unwrap_or(u64::MAX))
206 {
207 return Err(SqliteError::CapacityFloor {
208 volume: volume.display().to_string(),
209 available_bytes: available,
210 floor_bytes: self.floor_bytes,
211 required_headroom_bytes,
212 });
213 }
214 Ok(())
215 }
216
217 #[track_caller]
224 pub(crate) fn acquire(
225 &self,
226 class: crate::disk_guard::LeaseClass,
227 ) -> Result<Option<VolumeLease>, SqliteError> {
228 self.ensure_settled()?;
229 let Some(identity) = self.expected_volume.as_ref() else {
230 return Ok(None);
231 };
232 self.verify_current_volume()?;
233 #[cfg(test)]
234 if crate::disk_guard::SKIP_VOLUME_LEASE_FOR_MEASUREMENT.load(Ordering::Relaxed) {
235 self.verify_current_volume()?;
236 return Ok(Some(VolumeLease::unheld_for_measurement()));
237 }
238 let mut lease = match identity.acquire(self.guard_deadline, self.volume_lock_dir.as_deref())
239 {
240 Ok(lease) => lease,
241 Err(LeaseRefusal::TimedOut(error)) => {
242 self.record_lease_timeout(&error);
243 return Err(error);
244 }
245 Err(refusal) => return Err(refusal.into()),
246 };
247 self.verify_current_volume()?;
248 lease.classify(crate::disk_guard::effective_class(class));
249 Ok(Some(lease))
250 }
251
252 fn record_lease_timeout(&self, error: &SqliteError) {
257 self.lease_timeouts.fetch_add(1, Ordering::Relaxed);
258 let db = self
259 .database_path
260 .as_ref()
261 .map(|path| path.display().to_string())
262 .unwrap_or_else(|| "memory".to_string());
263 crate::timeout_sink::emit_lease_timeout(
264 &db,
265 &error.to_string(),
266 self.guard_deadline.as_millis().min(u128::from(u64::MAX)) as u64,
267 );
268 }
269
270 pub(crate) fn lease_timeouts(&self) -> u64 {
271 self.lease_timeouts.load(Ordering::Relaxed)
272 }
273
274 pub(crate) fn check_for_vacuum(&self) -> Result<(), SqliteError> {
278 let headroom = self
279 .database_path
280 .as_deref()
281 .map(crate::vacuum_capacity::estimate_vacuum_headroom)
282 .transpose()?
283 .unwrap_or(0);
284 self.check_with_headroom(headroom)
285 }
286
287 #[cfg(test)]
288 pub(super) fn set_test_space_probe(
289 &self,
290 probe: impl Fn(&Path) -> std::io::Result<u64> + Send + Sync + 'static,
291 ) {
292 *self.space_probe.lock() = Some(Arc::new(probe));
293 }
294
295 #[cfg(test)]
296 pub(crate) fn set_test_current_volume(&self, identity: Option<VolumeIdentity>) {
297 *self.current_volume_override.lock() = identity;
298 }
299
300 #[cfg(test)]
301 pub(crate) fn captured_volume_for_test(&self) -> Option<VolumeIdentity> {
302 self.expected_volume.clone()
303 }
304}
305
306#[derive(Clone, Copy)]
307pub(super) enum LogicalWriteOwner {
308 Request,
309 CoreMigration,
310 Schema,
311 AttachmentCutover,
312 Checkpoint,
313}
314
315pub struct WriterGuard<'pool> {
351 pub(super) guard: parking_lot::MutexGuard<'pool, ProgressConn>,
352 pub(super) origin: TxOrigin,
356 pub(super) pool: &'pool ConnectionPool,
357 pub(super) admission: &'pool WriteAdmission,
358 pub(super) logical_owner: LogicalWriteOwner,
359 pub(super) _volume_lease: Option<VolumeLease>,
362}
363
364pub(crate) struct PooledAutocommitWriteUnit<'pool> {
368 writer: WriterGuard<'pool>,
369}
370
371impl PooledAutocommitWriteUnit<'_> {
372 pub(crate) fn conn(&self) -> &ProgressConn {
373 self.writer.conn()
374 }
375
376 pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
377 self.writer.conn_mut()
378 }
379
380 pub(crate) fn rollback_or_retire(&mut self, context: &str) -> Result<(), SqliteError> {
381 self.writer.rollback_or_retire(context)
382 }
383}
384
385pub(crate) struct PooledTransactionWriteUnit<'pool> {
388 writer: WriterGuard<'pool>,
389}
390
391impl PooledTransactionWriteUnit<'_> {
392 pub(crate) fn conn(&self) -> &ProgressConn {
393 self.writer.conn()
394 }
395
396 pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
397 self.writer.conn_mut()
398 }
399}
400
401pub(crate) struct StandaloneWriteUnit {
405 conn: Option<Connection>,
406 admission: Arc<WriteAdmission>,
407 _volume_lease: Option<VolumeLease>,
408}
409
410impl StandaloneWriteUnit {
411 pub(super) fn new(
412 conn: Connection,
413 admission: Arc<WriteAdmission>,
414 volume_lease: Option<VolumeLease>,
415 ) -> Self {
416 Self {
417 conn: Some(conn),
418 admission,
419 _volume_lease: volume_lease,
420 }
421 }
422
423 pub(crate) fn conn(&self) -> &Connection {
424 self.conn
425 .as_ref()
426 .expect("standalone write unit owns its connection")
427 }
428}
429
430impl Drop for StandaloneWriteUnit {
431 fn drop(&mut self) {
432 let conn = self
433 .conn
434 .take()
435 .expect("standalone write unit retirement owner");
436 if conn.is_autocommit() {
437 drop(conn);
438 } else {
439 let _ = self.admission.close_retired_connection(conn);
442 }
443 }
444}
445
446pub struct CheckpointGuard<'pool> {
457 pub(super) guard: parking_lot::MutexGuard<'pool, ProgressConn>,
458}
459
460#[derive(Debug, Clone, Copy, PartialEq, Eq)]
462pub struct CheckpointResult {
463 pub busy: i64,
465 pub log_frames: i64,
467 pub checkpointed_frames: i64,
469}
470
471impl CheckpointGuard<'_> {
472 pub fn passive(&self) -> Result<CheckpointResult, SqliteError> {
474 self.guard
475 .query_row("PRAGMA wal_checkpoint(PASSIVE)", [], |row| {
476 Ok(CheckpointResult {
477 busy: row.get(0)?,
478 log_frames: row.get(1)?,
479 checkpointed_frames: row.get(2)?,
480 })
481 })
482 .map_err(Into::into)
483 }
484
485 pub fn truncate(&self) -> Result<CheckpointResult, SqliteError> {
487 self.guard
488 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |row| {
489 Ok(CheckpointResult {
490 busy: row.get(0)?,
491 log_frames: row.get(1)?,
492 checkpointed_frames: row.get(2)?,
493 })
494 })
495 .map_err(Into::into)
496 }
497}
498
499#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
508pub struct WriterAcquisitionSnapshot {
509 pub acquisitions: u64,
512 pub pooled_acquisitions: u64,
514 pub standalone_acquisitions: u64,
516 pub writer_task_acquisitions: u64,
519 pub timeouts: u64,
524 pub lease_timeouts: u64,
530 pub direct_busy_refusals: u64,
535 pub writer_task_begin_busy: u64,
540 pub writer_task_begin_busy_absorbed: u64,
545 pub writer_task_begin_errors: u64,
548 pub writer_task_request_failures: u64,
552 pub writer_task_side_effects_unknown: u64,
557 pub writer_guard_drop_rollbacks: u64,
564}
565
566#[derive(Debug, Default)]
570pub(crate) struct WriterAcquisitionCounters {
571 pub(super) pooled_acquisitions: AtomicU64,
572 pub(super) standalone_acquisitions: AtomicU64,
573 pub(super) writer_task_acquisitions: AtomicU64,
574 pub(super) pooled_timeouts: AtomicU64,
575 pub(super) direct_busy_refusals: AtomicU64,
576 pub(super) writer_task_begin_busy: AtomicU64,
577 pub(super) writer_task_begin_busy_absorbed: AtomicU64,
578 pub(super) writer_task_begin_errors: AtomicU64,
579 pub(super) writer_task_request_failures: AtomicU64,
580 pub(super) writer_task_side_effects_unknown: AtomicU64,
581 pub(super) writer_guard_drop_rollbacks: AtomicU64,
582}
583
584impl<'pool> WriterGuard<'pool> {
585 pub(crate) fn admit_autocommit(
589 mut self,
590 ) -> Result<PooledAutocommitWriteUnit<'pool>, SqliteError> {
591 if !self.guard.is_autocommit() {
592 self.pool.retire_pooled_writer(&mut self.guard);
593 return Err(SqliteError::InvalidData(
594 "pooled autocommit write began on a connection in a transaction".to_string(),
595 ));
596 }
597 self.ensure_logical_write_checkout(
598 "checkpoint writer checkout cannot admit a logical write",
599 )?;
600 self.admission.check()?;
601 Ok(PooledAutocommitWriteUnit { writer: self })
602 }
603
604 fn ensure_logical_write_checkout(&self, message: &'static str) -> Result<(), SqliteError> {
605 if matches!(self.logical_owner, LogicalWriteOwner::Checkpoint) {
606 return Err(SqliteError::InvalidData(message.to_string()));
607 }
608 if matches!(self.logical_owner, LogicalWriteOwner::Request) {
609 self.pool.ensure_request_write_route("pooled_write")?;
610 }
611 if self._volume_lease.is_none()
612 && self.pool.canonical_path().is_some()
613 && !self.pool.config.read_only
614 {
615 return Err(SqliteError::InvalidData(message.to_string()));
616 }
617 Ok(())
618 }
619
620 pub(crate) fn conn(&self) -> &ProgressConn {
622 &self.guard
623 }
624
625 pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
627 &mut self.guard
628 }
629
630 pub fn autocommit<R>(
654 self,
655 operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
656 ) -> Result<R, SqliteError> {
657 let mut unit = self.admit_autocommit()?;
658 let result = operation(unit.conn()).map_err(statement_error);
659 if unit.conn().is_autocommit() {
660 return result;
661 }
662 let rollback_proven = unit
663 .writer
664 .rollback_or_retire("autocommit script left its transaction open")
665 .is_ok();
666 settle_open_autocommit_result(
667 result,
668 rollback_proven,
669 "pooled script left a transaction open; rolled back",
670 )
671 }
672
673 #[cfg(any(test, feature = "test-support"))]
677 pub fn autocommit_sqlite<R>(
678 self,
679 operation: impl FnOnce(&Connection) -> rusqlite::Result<R>,
680 ) -> Result<R, SqliteError> {
681 self.autocommit(|conn| operation(conn).map_err(Into::into))
682 }
683
684 pub fn transaction<F, R>(self, f: F) -> Result<R, SqliteError>
694 where
695 F: FnOnce(&Connection) -> Result<R, SqliteError>,
696 {
697 let mut tx_handle = None;
698 let mut writer = self;
699 writer.ensure_logical_write_checkout(
700 "checkpoint writer checkout cannot start a logical transaction",
701 )?;
702 writer.begin_admitted_transaction()?;
703 let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
704 Some("writer_guard_tx".to_string()),
705 writer.origin.clone(),
706 ));
707
708 match f(&writer.guard) {
709 Ok(result) => {
710 if let Err(err) = writer.guard.execute_batch("COMMIT") {
711 if writer.rollback_or_retire("commit failure").is_err() {
712 return Err(SqliteError::settlement_with_cause(
713 &err,
714 khive_storage::error::SqliteWriteStage::Commit,
715 ));
716 }
717 return Err(SqliteError::write(
718 err,
719 khive_storage::error::SqliteWriteStage::Commit,
720 ));
721 }
722 if !writer.guard.is_autocommit() {
723 writer.pool.retire_pooled_writer(&mut writer.guard);
724 return Err(SqliteError::WriterSettlementUnknown);
725 }
726 Ok(result)
727 }
728 Err(err) => {
729 if writer
730 .rollback_or_retire("transaction body failure")
731 .is_err()
732 {
733 return Err(SqliteError::settlement_with_cause(
734 &err,
735 khive_storage::error::SqliteWriteStage::Statement,
736 ));
737 }
738 Err(match err {
739 SqliteError::Rusqlite(error) => {
740 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
741 }
742 other => other,
743 })
744 }
745 }
746 }
747
748 fn begin_admitted_transaction(&mut self) -> Result<(), SqliteError> {
750 self.ensure_logical_write_checkout("checkpoint writer cannot begin a logical transaction")?;
751 if !self.guard.is_autocommit() {
752 self.pool.retire_pooled_writer(&mut self.guard);
753 return Err(SqliteError::InheritedWriterTransaction);
754 }
755 if let Err(error) = self.guard.execute_batch("BEGIN IMMEDIATE") {
756 if !self.guard.is_autocommit() {
757 self.pool.retire_pooled_writer(&mut self.guard);
758 return Err(SqliteError::settlement_with_cause(
759 &error,
760 khive_storage::error::SqliteWriteStage::Begin,
761 ));
762 }
763 return Err(SqliteError::write(
764 error,
765 khive_storage::error::SqliteWriteStage::Begin,
766 ));
767 }
768 if let Err(error) = self.admission.check() {
769 self.rollback_or_retire("capacity admission")?;
770 return Err(error);
771 }
772 Ok(())
773 }
774
775 pub(crate) fn rollback_or_retire(&mut self, context: &str) -> Result<(), SqliteError> {
776 if !crate::connection_settlement::rollback_proves_autocommit(&self.guard) {
777 self.pool.retire_pooled_writer(&mut self.guard);
778 tracing::error!(context, "pooled writer rollback did not prove autocommit");
779 return Err(SqliteError::WriterSettlementUnknown);
780 }
781 Ok(())
782 }
783}
784
785pub(crate) struct PooledMigrationTransactions<'pool> {
787 pool: &'pool ConnectionPool,
788}
789
790impl crate::migrations::MigrationTransactions for PooledMigrationTransactions<'_> {
791 fn admitted<T>(
792 &mut self,
793 operation: impl FnOnce(&mut Connection) -> Result<T, SqliteError>,
794 ) -> Result<T, SqliteError> {
795 let mut writer = {
796 let _class =
797 crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Migration);
798 self.pool.writer_for_core_migration()?
799 };
800 let result = writer.conn_mut().with_mut(operation);
801 if writer.guard.is_autocommit() {
802 return result;
803 }
804 writer.rollback_or_retire("schema migration left its transaction open")?;
805 result.and(Err(SqliteError::WriterSettlementUnknown))
807 }
808}
809
810impl Drop for WriterGuard<'_> {
811 fn drop(&mut self) {
812 if !self.guard.is_autocommit() {
813 let settlement = self.rollback_or_retire("guard dropped with open transaction");
817 self.pool.record_writer_guard_drop(&settlement);
818 }
819 if self.pool.pooled_writer_retired.load(Ordering::Acquire) {
820 if let Some(replacement) = self.pool.retirement_connection.lock().take() {
821 let original = std::mem::replace(&mut *self.guard, replacement);
823 let _ = self
824 .admission
825 .close_retired_connection(original.into_inner());
826 }
827 }
828 }
829}
830
831impl ConnectionPool {
832 pub(crate) fn ensure_request_write_route(
833 &self,
834 operation: &'static str,
835 ) -> Result<(), SqliteError> {
836 if self.config.write_routing_strict {
837 Err(SqliteError::WriterRouteViolation { operation })
838 } else {
839 Ok(())
840 }
841 }
842
843 #[track_caller]
859 pub fn standalone_autocommit<R>(
860 &self,
861 operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
862 ) -> Result<R, SqliteError> {
863 let unit = self.standalone_write_unit()?;
864 self.write_admission.check()?;
865 let result = operation(unit.conn()).map_err(statement_error);
866 if unit.conn().is_autocommit() {
867 return result;
868 }
869 let rollback_proven = crate::connection_settlement::rollback_proves_autocommit(unit.conn());
870 settle_open_autocommit_result(
871 result,
872 rollback_proven,
873 "standalone script left a transaction open; rolled back",
874 )
875 }
876
877 #[track_caller]
884 pub fn standalone_transaction<R>(
885 &self,
886 operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
887 ) -> Result<R, SqliteError> {
888 let mut tx_handle = None;
889 let unit = self.standalone_transaction_write_unit()?;
890 let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
891 Some("standalone_transaction".into()),
892 self.origin(),
893 ));
894 match operation(unit.conn()).map_err(statement_error) {
895 Ok(value) => match unit.conn().execute_batch("COMMIT") {
896 Ok(()) if unit.conn().is_autocommit() => Ok(value),
897 Ok(()) => Err(SqliteError::WriterSettlementUnknown),
898 Err(error) => {
899 if unit.conn().execute_batch("ROLLBACK").is_err()
900 || !unit.conn().is_autocommit()
901 {
902 return Err(SqliteError::settlement_with_cause(
903 &error,
904 khive_storage::error::SqliteWriteStage::Commit,
905 ));
906 }
907 Err(SqliteError::write(
908 error,
909 khive_storage::error::SqliteWriteStage::Commit,
910 ))
911 }
912 },
913 Err(error) => {
914 if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
915 return Err(SqliteError::settlement_with_cause(
916 &error,
917 khive_storage::error::SqliteWriteStage::Statement,
918 ));
919 }
920 Err(error)
921 }
922 }
923 }
924
925 #[track_caller]
926 pub(crate) fn autocommit_write_unit(
927 &self,
928 ) -> Result<PooledAutocommitWriteUnit<'_>, SqliteError> {
929 self.writer()?.admit_autocommit()
930 }
931
932 #[track_caller]
933 pub(crate) fn transaction_write_unit(
934 &self,
935 ) -> Result<super::PooledTransactionWriteUnit<'_>, SqliteError> {
936 let mut writer = self.writer()?;
937 writer.begin_admitted_transaction()?;
938 Ok(PooledTransactionWriteUnit { writer })
939 }
940
941 #[track_caller]
946 pub(crate) fn execute_direct_transaction<R, F>(
947 &self,
948 capability: StorageCapability,
949 operation: &'static str,
950 f: F,
951 ) -> Result<R, StorageError>
952 where
953 F: FnOnce(&Connection) -> Result<R, StorageError>,
954 {
955 let _tx_handle =
956 khive_storage::tx_registry::register_scoped(Some(operation.to_string()), self.origin());
957 let db_label = crate::timeout_sink::db_label(self);
958 let map_admission_error = |error: SqliteError| {
959 crate::timeout_sink::maybe_emit_sqlite_full(&db_label, &error);
960 let error = error.into_storage_error(capability, operation);
961 self.record_direct_writer_error(&error);
962 error
963 };
964 let result = if self.canonical_path().is_some() {
965 let unit = self
966 .standalone_transaction_write_unit()
967 .map_err(map_admission_error)?;
968 let (result, _) = execute_wrapped_transaction(unit.conn(), operation, f);
969 result
970 } else {
971 let mut unit = self.transaction_write_unit().map_err(map_admission_error)?;
972 let (result, terminal_state) = execute_wrapped_transaction(unit.conn(), operation, f);
973 if terminal_state.is_some() {
974 self.retire_pooled_writer(unit.conn_mut());
975 }
976 result
977 };
978 if let Err(error) = &result {
979 crate::timeout_sink::maybe_emit_sqlite_full(&db_label, error);
980 self.record_direct_writer_error(error);
981 }
982 result
983 }
984
985 pub fn run_migrations(&self) -> Result<u32, SqliteError> {
988 if self.config.read_only {
989 return Err(SqliteError::InvalidData(
990 "cannot run migrations on a read-only pool".to_string(),
991 ));
992 }
993 let owner = crate::stores::blob::acquire_database_gc_owner_for_path_blocking(
994 self.canonical_path().map(Path::to_path_buf),
995 )
996 .map_err(|error| {
997 SqliteError::InvalidData(format!(
998 "failed to acquire database GC owner before schema migration: {error}"
999 ))
1000 })?;
1001 crate::migrations::run_migrations_with_database_gc_owner(
1002 &mut self.migration_transactions(),
1003 &owner,
1004 &self.write_admission,
1005 )
1006 }
1007
1008 pub(crate) fn migration_transactions(&self) -> PooledMigrationTransactions<'_> {
1012 PooledMigrationTransactions { pool: self }
1013 }
1014
1015 #[track_caller]
1019 pub(crate) fn standalone_transaction_write_unit(
1020 &self,
1021 ) -> Result<super::StandaloneWriteUnit, SqliteError> {
1022 let unit = self.standalone_write_unit()?;
1023 self.begin_standalone_transaction(unit)
1024 }
1025
1026 #[track_caller]
1029 pub(crate) fn standalone_sql_bridge_transaction_write_unit(
1030 &self,
1031 ) -> Result<super::StandaloneWriteUnit, StorageError> {
1032 let unit = self
1033 .standalone_write_unit()
1034 .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
1035 for (name, value) in [
1036 ("cache_size", sqlite_cache_size_pragma()),
1037 ("mmap_size", sqlite_mmap_size_pragma()),
1038 ] {
1039 unit.conn()
1040 .pragma_update(None, name, value)
1041 .map_err(|error| {
1042 StorageError::driver(StorageCapability::Sql, "open_writer", error)
1043 })?;
1044 }
1045 self.begin_standalone_transaction(unit)
1046 .map_err(|error| match error {
1047 SqliteError::Write { stage, source } => {
1048 crate::timeout_sink::maybe_emit_busy(
1049 &crate::timeout_sink::db_label(self),
1050 crate::timeout_sink::Site::StandaloneSqlBridge,
1051 &source,
1052 );
1053 crate::error::with_write_stage(
1054 StorageError::driver(StorageCapability::Sql, "execute", source),
1055 stage,
1056 )
1057 }
1058 SqliteError::Rusqlite(source) => {
1059 crate::timeout_sink::maybe_emit_busy(
1060 &crate::timeout_sink::db_label(self),
1061 crate::timeout_sink::Site::StandaloneSqlBridge,
1062 &source,
1063 );
1064 StorageError::driver(StorageCapability::Sql, "execute", source)
1065 }
1066 error => error.into_storage_error(StorageCapability::Sql, "execute"),
1067 })
1068 }
1069
1070 fn begin_standalone_transaction(
1071 &self,
1072 unit: StandaloneWriteUnit,
1073 ) -> Result<StandaloneWriteUnit, SqliteError> {
1074 if let Err(error) = unit.conn().execute_batch("BEGIN IMMEDIATE") {
1075 if !unit.conn().is_autocommit() {
1076 return Err(SqliteError::settlement_with_cause(
1077 &error,
1078 khive_storage::error::SqliteWriteStage::Begin,
1079 ));
1080 }
1081 return Err(SqliteError::write(
1082 error,
1083 khive_storage::error::SqliteWriteStage::Begin,
1084 ));
1085 }
1086 if let Err(error) = self.write_admission.check() {
1087 if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
1088 return Err(SqliteError::WriterSettlementUnknown);
1089 }
1090 return Err(error);
1091 }
1092 Ok(unit)
1093 }
1094}
1095
1096fn settle_open_autocommit_result<R>(
1097 result: Result<R, SqliteError>,
1098 rollback_proven: bool,
1099 left_open_message: &'static str,
1100) -> Result<R, SqliteError> {
1101 match (rollback_proven, result) {
1102 (true, result) => result.and(Err(SqliteError::InvalidData(left_open_message.into()))),
1103 (false, Err(error)) => Err(SqliteError::settlement_with_cause(
1104 &error,
1105 khive_storage::error::SqliteWriteStage::Statement,
1106 )),
1107 (false, Ok(_)) => Err(SqliteError::WriterSettlementUnknown),
1108 }
1109}
1110
1111fn statement_error(error: SqliteError) -> SqliteError {
1112 match error {
1113 SqliteError::Rusqlite(error) => {
1114 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
1115 }
1116 other => other,
1117 }
1118}
1119
1120#[cfg(test)]
1121#[path = "standalone_write_tests.rs"]
1122mod standalone_write_tests;
1123
1124#[cfg(test)]
1125#[path = "pooled_write_tests.rs"]
1126mod pooled_write_tests;
1127
1128#[cfg(test)]
1129mod routing_authority_tests {
1130 use super::*;
1131
1132 #[test]
1133 fn checkpoint_owner_never_grants_memory_logical_write_authority() {
1134 for strict in [false, true] {
1135 let pool = ConnectionPool::new(PoolConfig {
1136 write_routing_strict: strict,
1137 write_queue_enabled: Some(false),
1138 ..PoolConfig::for_test()
1139 })
1140 .unwrap();
1141 let called = std::cell::Cell::new(false);
1142 let result = pool
1143 .writer_for_checkpoint_operation()
1144 .unwrap()
1145 .autocommit(|_| {
1146 called.set(true);
1147 Ok(())
1148 });
1149 assert!(
1150 matches!(result, Err(SqliteError::InvalidData(_))),
1151 "checkpoint authority cannot admit a logical write on a memory pool: {result:?}"
1152 );
1153 assert!(
1154 !called.get(),
1155 "checkpoint refusal must precede the write callback"
1156 );
1157 }
1158 }
1159}