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
306pub struct WriterGuard<'pool> {
342 pub(super) guard: parking_lot::MutexGuard<'pool, ProgressConn>,
343 pub(super) origin: TxOrigin,
347 pub(super) pool: &'pool ConnectionPool,
348 pub(super) admission: &'pool WriteAdmission,
349 pub(super) _volume_lease: Option<VolumeLease>,
352}
353
354pub(crate) struct PooledAutocommitWriteUnit<'pool> {
358 writer: WriterGuard<'pool>,
359}
360
361impl PooledAutocommitWriteUnit<'_> {
362 pub(crate) fn conn(&self) -> &ProgressConn {
363 self.writer.conn()
364 }
365
366 pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
367 self.writer.conn_mut()
368 }
369
370 pub(crate) fn rollback_or_retire(&mut self, context: &str) -> Result<(), SqliteError> {
371 self.writer.rollback_or_retire(context)
372 }
373}
374
375pub(crate) struct PooledTransactionWriteUnit<'pool> {
378 writer: WriterGuard<'pool>,
379}
380
381impl PooledTransactionWriteUnit<'_> {
382 pub(crate) fn conn(&self) -> &ProgressConn {
383 self.writer.conn()
384 }
385
386 pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
387 self.writer.conn_mut()
388 }
389}
390
391pub(crate) struct StandaloneWriteUnit {
395 conn: Option<Connection>,
396 admission: Arc<WriteAdmission>,
397 _volume_lease: Option<VolumeLease>,
398}
399
400impl StandaloneWriteUnit {
401 pub(super) fn new(
402 conn: Connection,
403 admission: Arc<WriteAdmission>,
404 volume_lease: Option<VolumeLease>,
405 ) -> Self {
406 Self {
407 conn: Some(conn),
408 admission,
409 _volume_lease: volume_lease,
410 }
411 }
412
413 pub(crate) fn conn(&self) -> &Connection {
414 self.conn
415 .as_ref()
416 .expect("standalone write unit owns its connection")
417 }
418}
419
420impl Drop for StandaloneWriteUnit {
421 fn drop(&mut self) {
422 let conn = self
423 .conn
424 .take()
425 .expect("standalone write unit retirement owner");
426 if conn.is_autocommit() {
427 drop(conn);
428 } else {
429 let _ = self.admission.close_retired_connection(conn);
432 }
433 }
434}
435
436pub struct CheckpointGuard<'pool> {
447 pub(super) guard: parking_lot::MutexGuard<'pool, ProgressConn>,
448}
449
450#[derive(Debug, Clone, Copy, PartialEq, Eq)]
452pub struct CheckpointResult {
453 pub busy: i64,
455 pub log_frames: i64,
457 pub checkpointed_frames: i64,
459}
460
461impl CheckpointGuard<'_> {
462 pub fn passive(&self) -> Result<CheckpointResult, SqliteError> {
464 self.guard
465 .query_row("PRAGMA wal_checkpoint(PASSIVE)", [], |row| {
466 Ok(CheckpointResult {
467 busy: row.get(0)?,
468 log_frames: row.get(1)?,
469 checkpointed_frames: row.get(2)?,
470 })
471 })
472 .map_err(Into::into)
473 }
474
475 pub fn truncate(&self) -> Result<CheckpointResult, SqliteError> {
477 self.guard
478 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |row| {
479 Ok(CheckpointResult {
480 busy: row.get(0)?,
481 log_frames: row.get(1)?,
482 checkpointed_frames: row.get(2)?,
483 })
484 })
485 .map_err(Into::into)
486 }
487}
488
489#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
498pub struct WriterAcquisitionSnapshot {
499 pub acquisitions: u64,
502 pub pooled_acquisitions: u64,
504 pub standalone_acquisitions: u64,
506 pub writer_task_acquisitions: u64,
509 pub timeouts: u64,
514 pub lease_timeouts: u64,
520 pub direct_busy_refusals: u64,
525 pub writer_task_begin_busy: u64,
530 pub writer_task_begin_busy_absorbed: u64,
535 pub writer_task_begin_errors: u64,
538 pub writer_task_request_failures: u64,
542 pub writer_task_side_effects_unknown: u64,
547 pub writer_guard_drop_rollbacks: u64,
554}
555
556#[derive(Debug, Default)]
560pub(crate) struct WriterAcquisitionCounters {
561 pub(super) pooled_acquisitions: AtomicU64,
562 pub(super) standalone_acquisitions: AtomicU64,
563 pub(super) writer_task_acquisitions: AtomicU64,
564 pub(super) pooled_timeouts: AtomicU64,
565 pub(super) direct_busy_refusals: AtomicU64,
566 pub(super) writer_task_begin_busy: AtomicU64,
567 pub(super) writer_task_begin_busy_absorbed: AtomicU64,
568 pub(super) writer_task_begin_errors: AtomicU64,
569 pub(super) writer_task_request_failures: AtomicU64,
570 pub(super) writer_task_side_effects_unknown: AtomicU64,
571 pub(super) writer_guard_drop_rollbacks: AtomicU64,
572}
573
574impl<'pool> WriterGuard<'pool> {
575 pub(crate) fn admit_autocommit(
579 mut self,
580 ) -> Result<PooledAutocommitWriteUnit<'pool>, SqliteError> {
581 if !self.guard.is_autocommit() {
582 self.pool.retire_pooled_writer(&mut self.guard);
583 return Err(SqliteError::InvalidData(
584 "pooled autocommit write began on a connection in a transaction".to_string(),
585 ));
586 }
587 self.ensure_logical_write_checkout(
588 "checkpoint writer checkout cannot admit a logical write",
589 )?;
590 self.admission.check()?;
591 Ok(PooledAutocommitWriteUnit { writer: self })
592 }
593
594 fn ensure_logical_write_checkout(&self, message: &'static str) -> Result<(), SqliteError> {
595 if self._volume_lease.is_none()
596 && self.pool.canonical_path().is_some()
597 && !self.pool.config.read_only
598 {
599 return Err(SqliteError::InvalidData(message.to_string()));
600 }
601 Ok(())
602 }
603
604 pub(crate) fn conn(&self) -> &ProgressConn {
606 &self.guard
607 }
608
609 pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
611 &mut self.guard
612 }
613
614 pub fn autocommit<R>(
638 self,
639 operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
640 ) -> Result<R, SqliteError> {
641 let mut unit = self.admit_autocommit()?;
642 let result = operation(unit.conn()).map_err(statement_error);
643 if unit.conn().is_autocommit() {
644 return result;
645 }
646 let rollback_proven = unit
647 .writer
648 .rollback_or_retire("autocommit script left its transaction open")
649 .is_ok();
650 settle_open_autocommit_result(
651 result,
652 rollback_proven,
653 "pooled script left a transaction open; rolled back",
654 )
655 }
656
657 #[cfg(any(test, feature = "test-support"))]
661 pub fn autocommit_sqlite<R>(
662 self,
663 operation: impl FnOnce(&Connection) -> rusqlite::Result<R>,
664 ) -> Result<R, SqliteError> {
665 self.autocommit(|conn| operation(conn).map_err(Into::into))
666 }
667
668 pub fn transaction<F, R>(self, f: F) -> Result<R, SqliteError>
678 where
679 F: FnOnce(&Connection) -> Result<R, SqliteError>,
680 {
681 let mut tx_handle = None;
682 let mut writer = self;
683 writer.ensure_logical_write_checkout(
684 "checkpoint writer checkout cannot start a logical transaction",
685 )?;
686 writer.begin_admitted_transaction()?;
687 let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
688 Some("writer_guard_tx".to_string()),
689 writer.origin.clone(),
690 ));
691
692 match f(&writer.guard) {
693 Ok(result) => {
694 if let Err(err) = writer.guard.execute_batch("COMMIT") {
695 if writer.rollback_or_retire("commit failure").is_err() {
696 return Err(SqliteError::settlement_with_cause(
697 &err,
698 khive_storage::error::SqliteWriteStage::Commit,
699 ));
700 }
701 return Err(SqliteError::write(
702 err,
703 khive_storage::error::SqliteWriteStage::Commit,
704 ));
705 }
706 if !writer.guard.is_autocommit() {
707 writer.pool.retire_pooled_writer(&mut writer.guard);
708 return Err(SqliteError::WriterSettlementUnknown);
709 }
710 Ok(result)
711 }
712 Err(err) => {
713 if writer
714 .rollback_or_retire("transaction body failure")
715 .is_err()
716 {
717 return Err(SqliteError::settlement_with_cause(
718 &err,
719 khive_storage::error::SqliteWriteStage::Statement,
720 ));
721 }
722 Err(match err {
723 SqliteError::Rusqlite(error) => {
724 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
725 }
726 other => other,
727 })
728 }
729 }
730 }
731
732 fn begin_admitted_transaction(&mut self) -> Result<(), SqliteError> {
734 if !self.guard.is_autocommit() {
735 self.pool.retire_pooled_writer(&mut self.guard);
736 return Err(SqliteError::InheritedWriterTransaction);
737 }
738 if let Err(error) = self.guard.execute_batch("BEGIN IMMEDIATE") {
739 if !self.guard.is_autocommit() {
740 self.pool.retire_pooled_writer(&mut self.guard);
741 return Err(SqliteError::settlement_with_cause(
742 &error,
743 khive_storage::error::SqliteWriteStage::Begin,
744 ));
745 }
746 return Err(SqliteError::write(
747 error,
748 khive_storage::error::SqliteWriteStage::Begin,
749 ));
750 }
751 if let Err(error) = self.admission.check() {
752 self.rollback_or_retire("capacity admission")?;
753 return Err(error);
754 }
755 Ok(())
756 }
757
758 pub(crate) fn rollback_or_retire(&mut self, context: &str) -> Result<(), SqliteError> {
759 if !crate::connection_settlement::rollback_proves_autocommit(&self.guard) {
760 self.pool.retire_pooled_writer(&mut self.guard);
761 tracing::error!(context, "pooled writer rollback did not prove autocommit");
762 return Err(SqliteError::WriterSettlementUnknown);
763 }
764 Ok(())
765 }
766}
767
768pub(crate) struct PooledMigrationTransactions<'pool> {
770 pool: &'pool ConnectionPool,
771}
772
773impl crate::migrations::MigrationTransactions for PooledMigrationTransactions<'_> {
774 fn admitted<T>(
775 &mut self,
776 operation: impl FnOnce(&mut Connection) -> Result<T, SqliteError>,
777 ) -> Result<T, SqliteError> {
778 let mut writer = {
779 let _class =
780 crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Migration);
781 self.pool.writer()?
782 };
783 let result = writer.conn_mut().with_mut(operation);
784 if writer.guard.is_autocommit() {
785 return result;
786 }
787 writer.rollback_or_retire("schema migration left its transaction open")?;
788 result.and(Err(SqliteError::WriterSettlementUnknown))
790 }
791}
792
793impl Drop for WriterGuard<'_> {
794 fn drop(&mut self) {
795 if !self.guard.is_autocommit() {
796 let settlement = self.rollback_or_retire("guard dropped with open transaction");
800 self.pool.record_writer_guard_drop(&settlement);
801 }
802 if self.pool.pooled_writer_retired.load(Ordering::Acquire) {
803 if let Some(replacement) = self.pool.retirement_connection.lock().take() {
804 let original = std::mem::replace(&mut *self.guard, replacement);
806 let _ = self
807 .admission
808 .close_retired_connection(original.into_inner());
809 }
810 }
811 }
812}
813
814impl ConnectionPool {
815 #[track_caller]
831 pub fn standalone_autocommit<R>(
832 &self,
833 operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
834 ) -> Result<R, SqliteError> {
835 let unit = self.standalone_write_unit()?;
836 self.write_admission.check()?;
837 let result = operation(unit.conn()).map_err(statement_error);
838 if unit.conn().is_autocommit() {
839 return result;
840 }
841 let rollback_proven = crate::connection_settlement::rollback_proves_autocommit(unit.conn());
842 settle_open_autocommit_result(
843 result,
844 rollback_proven,
845 "standalone script left a transaction open; rolled back",
846 )
847 }
848
849 #[track_caller]
856 pub fn standalone_transaction<R>(
857 &self,
858 operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
859 ) -> Result<R, SqliteError> {
860 let mut tx_handle = None;
861 let unit = self.standalone_transaction_write_unit()?;
862 let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
863 Some("standalone_transaction".into()),
864 self.origin(),
865 ));
866 match operation(unit.conn()).map_err(statement_error) {
867 Ok(value) => match unit.conn().execute_batch("COMMIT") {
868 Ok(()) if unit.conn().is_autocommit() => Ok(value),
869 Ok(()) => Err(SqliteError::WriterSettlementUnknown),
870 Err(error) => {
871 if unit.conn().execute_batch("ROLLBACK").is_err()
872 || !unit.conn().is_autocommit()
873 {
874 return Err(SqliteError::settlement_with_cause(
875 &error,
876 khive_storage::error::SqliteWriteStage::Commit,
877 ));
878 }
879 Err(SqliteError::write(
880 error,
881 khive_storage::error::SqliteWriteStage::Commit,
882 ))
883 }
884 },
885 Err(error) => {
886 if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
887 return Err(SqliteError::settlement_with_cause(
888 &error,
889 khive_storage::error::SqliteWriteStage::Statement,
890 ));
891 }
892 Err(error)
893 }
894 }
895 }
896
897 #[track_caller]
898 pub(crate) fn autocommit_write_unit(
899 &self,
900 ) -> Result<PooledAutocommitWriteUnit<'_>, SqliteError> {
901 self.writer()?.admit_autocommit()
902 }
903
904 #[track_caller]
905 pub(crate) fn transaction_write_unit(
906 &self,
907 ) -> Result<super::PooledTransactionWriteUnit<'_>, SqliteError> {
908 let mut writer = self.writer()?;
909 writer.begin_admitted_transaction()?;
910 Ok(PooledTransactionWriteUnit { writer })
911 }
912
913 #[track_caller]
918 pub(crate) fn execute_direct_transaction<R, F>(
919 &self,
920 capability: StorageCapability,
921 operation: &'static str,
922 f: F,
923 ) -> Result<R, StorageError>
924 where
925 F: FnOnce(&Connection) -> Result<R, StorageError>,
926 {
927 let _tx_handle =
928 khive_storage::tx_registry::register_scoped(Some(operation.to_string()), self.origin());
929 let db_label = crate::timeout_sink::db_label(self);
930 let map_admission_error = |error: SqliteError| {
931 crate::timeout_sink::maybe_emit_sqlite_full(&db_label, &error);
932 let error = error.into_storage_error(capability, operation);
933 self.record_direct_writer_error(&error);
934 error
935 };
936 let result = if self.canonical_path().is_some() {
937 let unit = self
938 .standalone_transaction_write_unit()
939 .map_err(map_admission_error)?;
940 let (result, _) = execute_wrapped_transaction(unit.conn(), operation, f);
941 result
942 } else {
943 let mut unit = self.transaction_write_unit().map_err(map_admission_error)?;
944 let (result, terminal_state) = execute_wrapped_transaction(unit.conn(), operation, f);
945 if terminal_state.is_some() {
946 self.retire_pooled_writer(unit.conn_mut());
947 }
948 result
949 };
950 if let Err(error) = &result {
951 crate::timeout_sink::maybe_emit_sqlite_full(&db_label, error);
952 self.record_direct_writer_error(error);
953 }
954 result
955 }
956
957 pub fn run_migrations(&self) -> Result<u32, SqliteError> {
960 if self.config.read_only {
961 return Err(SqliteError::InvalidData(
962 "cannot run migrations on a read-only pool".to_string(),
963 ));
964 }
965 let owner = crate::stores::blob::acquire_database_gc_owner_for_path_blocking(
966 self.canonical_path().map(Path::to_path_buf),
967 )
968 .map_err(|error| {
969 SqliteError::InvalidData(format!(
970 "failed to acquire database GC owner before schema migration: {error}"
971 ))
972 })?;
973 crate::migrations::run_migrations_with_database_gc_owner(
974 &mut self.migration_transactions(),
975 &owner,
976 &self.write_admission,
977 )
978 }
979
980 pub(crate) fn migration_transactions(&self) -> PooledMigrationTransactions<'_> {
984 PooledMigrationTransactions { pool: self }
985 }
986
987 #[track_caller]
991 pub(crate) fn standalone_transaction_write_unit(
992 &self,
993 ) -> Result<super::StandaloneWriteUnit, SqliteError> {
994 let unit = self.standalone_write_unit()?;
995 self.begin_standalone_transaction(unit)
996 }
997
998 #[track_caller]
1001 pub(crate) fn standalone_sql_bridge_transaction_write_unit(
1002 &self,
1003 ) -> Result<super::StandaloneWriteUnit, StorageError> {
1004 let unit = self
1005 .standalone_write_unit()
1006 .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
1007 for (name, value) in [
1008 ("cache_size", sqlite_cache_size_pragma()),
1009 ("mmap_size", sqlite_mmap_size_pragma()),
1010 ] {
1011 unit.conn()
1012 .pragma_update(None, name, value)
1013 .map_err(|error| {
1014 StorageError::driver(StorageCapability::Sql, "open_writer", error)
1015 })?;
1016 }
1017 self.begin_standalone_transaction(unit)
1018 .map_err(|error| match error {
1019 SqliteError::Write { stage, source } => {
1020 crate::timeout_sink::maybe_emit_busy(
1021 &crate::timeout_sink::db_label(self),
1022 crate::timeout_sink::Site::StandaloneSqlBridge,
1023 &source,
1024 );
1025 crate::error::with_write_stage(
1026 StorageError::driver(StorageCapability::Sql, "execute", source),
1027 stage,
1028 )
1029 }
1030 SqliteError::Rusqlite(source) => {
1031 crate::timeout_sink::maybe_emit_busy(
1032 &crate::timeout_sink::db_label(self),
1033 crate::timeout_sink::Site::StandaloneSqlBridge,
1034 &source,
1035 );
1036 StorageError::driver(StorageCapability::Sql, "execute", source)
1037 }
1038 error => error.into_storage_error(StorageCapability::Sql, "execute"),
1039 })
1040 }
1041
1042 fn begin_standalone_transaction(
1043 &self,
1044 unit: StandaloneWriteUnit,
1045 ) -> Result<StandaloneWriteUnit, SqliteError> {
1046 if let Err(error) = unit.conn().execute_batch("BEGIN IMMEDIATE") {
1047 if !unit.conn().is_autocommit() {
1048 return Err(SqliteError::settlement_with_cause(
1049 &error,
1050 khive_storage::error::SqliteWriteStage::Begin,
1051 ));
1052 }
1053 return Err(SqliteError::write(
1054 error,
1055 khive_storage::error::SqliteWriteStage::Begin,
1056 ));
1057 }
1058 if let Err(error) = self.write_admission.check() {
1059 if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
1060 return Err(SqliteError::WriterSettlementUnknown);
1061 }
1062 return Err(error);
1063 }
1064 Ok(unit)
1065 }
1066}
1067
1068fn settle_open_autocommit_result<R>(
1069 result: Result<R, SqliteError>,
1070 rollback_proven: bool,
1071 left_open_message: &'static str,
1072) -> Result<R, SqliteError> {
1073 match (rollback_proven, result) {
1074 (true, result) => result.and(Err(SqliteError::InvalidData(left_open_message.into()))),
1075 (false, Err(error)) => Err(SqliteError::settlement_with_cause(
1076 &error,
1077 khive_storage::error::SqliteWriteStage::Statement,
1078 )),
1079 (false, Ok(_)) => Err(SqliteError::WriterSettlementUnknown),
1080 }
1081}
1082
1083fn statement_error(error: SqliteError) -> SqliteError {
1084 match error {
1085 SqliteError::Rusqlite(error) => {
1086 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
1087 }
1088 other => other,
1089 }
1090}
1091
1092#[cfg(test)]
1093#[path = "standalone_write_tests.rs"]
1094mod standalone_write_tests;
1095
1096#[cfg(test)]
1097#[path = "pooled_write_tests.rs"]
1098mod pooled_write_tests;