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]
222 pub(crate) fn acquire(&self) -> Result<Option<VolumeLease>, SqliteError> {
223 self.ensure_settled()?;
224 let Some(identity) = self.expected_volume.as_ref() else {
225 return Ok(None);
226 };
227 self.verify_current_volume()?;
228 #[cfg(test)]
229 if crate::disk_guard::SKIP_VOLUME_LEASE_FOR_MEASUREMENT.load(Ordering::Relaxed) {
230 self.verify_current_volume()?;
231 return Ok(Some(VolumeLease::unheld_for_measurement()));
232 }
233 let lease = match identity.acquire(self.guard_deadline, self.volume_lock_dir.as_deref()) {
234 Ok(lease) => lease,
235 Err(LeaseRefusal::TimedOut(error)) => {
236 self.record_lease_timeout(&error);
237 return Err(error);
238 }
239 Err(refusal) => return Err(refusal.into()),
240 };
241 self.verify_current_volume()?;
242 Ok(Some(lease))
243 }
244
245 fn record_lease_timeout(&self, error: &SqliteError) {
250 self.lease_timeouts.fetch_add(1, Ordering::Relaxed);
251 let db = self
252 .database_path
253 .as_ref()
254 .map(|path| path.display().to_string())
255 .unwrap_or_else(|| "memory".to_string());
256 crate::timeout_sink::emit_lease_timeout(
257 &db,
258 &error.to_string(),
259 self.guard_deadline.as_millis().min(u128::from(u64::MAX)) as u64,
260 );
261 }
262
263 pub(crate) fn lease_timeouts(&self) -> u64 {
264 self.lease_timeouts.load(Ordering::Relaxed)
265 }
266
267 pub(crate) fn check_for_vacuum(&self) -> Result<(), SqliteError> {
271 let headroom = self
272 .database_path
273 .as_deref()
274 .map(crate::vacuum_capacity::estimate_vacuum_headroom)
275 .transpose()?
276 .unwrap_or(0);
277 self.check_with_headroom(headroom)
278 }
279
280 #[cfg(test)]
281 pub(super) fn set_test_space_probe(
282 &self,
283 probe: impl Fn(&Path) -> std::io::Result<u64> + Send + Sync + 'static,
284 ) {
285 *self.space_probe.lock() = Some(Arc::new(probe));
286 }
287
288 #[cfg(test)]
289 pub(crate) fn set_test_current_volume(&self, identity: Option<VolumeIdentity>) {
290 *self.current_volume_override.lock() = identity;
291 }
292
293 #[cfg(test)]
294 pub(crate) fn captured_volume_for_test(&self) -> Option<VolumeIdentity> {
295 self.expected_volume.clone()
296 }
297}
298
299pub struct WriterGuard<'pool> {
335 pub(super) guard: parking_lot::MutexGuard<'pool, Connection>,
336 pub(super) origin: TxOrigin,
340 pub(super) pool: &'pool ConnectionPool,
341 pub(super) admission: &'pool WriteAdmission,
342 pub(super) _volume_lease: Option<VolumeLease>,
345}
346
347pub(crate) struct PooledAutocommitWriteUnit<'pool> {
351 writer: WriterGuard<'pool>,
352}
353
354impl PooledAutocommitWriteUnit<'_> {
355 pub(crate) fn conn(&self) -> &Connection {
356 self.writer.conn()
357 }
358
359 pub(crate) fn rollback_or_retire(&self, context: &str) -> Result<(), SqliteError> {
360 self.writer.rollback_or_retire(context)
361 }
362}
363
364pub(crate) struct PooledTransactionWriteUnit<'pool> {
367 writer: WriterGuard<'pool>,
368}
369
370impl PooledTransactionWriteUnit<'_> {
371 pub(crate) fn conn(&self) -> &Connection {
372 self.writer.conn()
373 }
374}
375
376pub(crate) struct StandaloneWriteUnit {
380 conn: Option<Connection>,
381 admission: Arc<WriteAdmission>,
382 _volume_lease: Option<VolumeLease>,
383}
384
385impl StandaloneWriteUnit {
386 pub(super) fn new(
387 conn: Connection,
388 admission: Arc<WriteAdmission>,
389 volume_lease: Option<VolumeLease>,
390 ) -> Self {
391 Self {
392 conn: Some(conn),
393 admission,
394 _volume_lease: volume_lease,
395 }
396 }
397
398 pub(crate) fn conn(&self) -> &Connection {
399 self.conn
400 .as_ref()
401 .expect("standalone write unit owns its connection")
402 }
403}
404
405impl Drop for StandaloneWriteUnit {
406 fn drop(&mut self) {
407 let conn = self
408 .conn
409 .take()
410 .expect("standalone write unit retirement owner");
411 if conn.is_autocommit() {
412 drop(conn);
413 } else {
414 let _ = self.admission.close_retired_connection(conn);
417 }
418 }
419}
420
421pub struct CheckpointGuard<'pool> {
432 pub(super) guard: parking_lot::MutexGuard<'pool, Connection>,
433}
434
435#[derive(Debug, Clone, Copy, PartialEq, Eq)]
437pub struct CheckpointResult {
438 pub busy: i64,
440 pub log_frames: i64,
442 pub checkpointed_frames: i64,
444}
445
446impl CheckpointGuard<'_> {
447 pub fn passive(&self) -> Result<CheckpointResult, SqliteError> {
449 self.guard
450 .query_row("PRAGMA wal_checkpoint(PASSIVE)", [], |row| {
451 Ok(CheckpointResult {
452 busy: row.get(0)?,
453 log_frames: row.get(1)?,
454 checkpointed_frames: row.get(2)?,
455 })
456 })
457 .map_err(Into::into)
458 }
459
460 pub fn truncate(&self) -> Result<CheckpointResult, SqliteError> {
462 self.guard
463 .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |row| {
464 Ok(CheckpointResult {
465 busy: row.get(0)?,
466 log_frames: row.get(1)?,
467 checkpointed_frames: row.get(2)?,
468 })
469 })
470 .map_err(Into::into)
471 }
472}
473
474#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
483pub struct WriterAcquisitionSnapshot {
484 pub acquisitions: u64,
487 pub pooled_acquisitions: u64,
489 pub standalone_acquisitions: u64,
491 pub writer_task_acquisitions: u64,
494 pub timeouts: u64,
499 pub lease_timeouts: u64,
505 pub direct_busy_refusals: u64,
510 pub writer_task_begin_busy: u64,
515 pub writer_task_begin_busy_absorbed: u64,
520 pub writer_task_begin_errors: u64,
523 pub writer_task_request_failures: u64,
527 pub writer_task_side_effects_unknown: u64,
532 pub writer_guard_drop_rollbacks: u64,
539}
540
541#[derive(Debug, Default)]
545pub(crate) struct WriterAcquisitionCounters {
546 pub(super) pooled_acquisitions: AtomicU64,
547 pub(super) standalone_acquisitions: AtomicU64,
548 pub(super) writer_task_acquisitions: AtomicU64,
549 pub(super) pooled_timeouts: AtomicU64,
550 pub(super) direct_busy_refusals: AtomicU64,
551 pub(super) writer_task_begin_busy: AtomicU64,
552 pub(super) writer_task_begin_busy_absorbed: AtomicU64,
553 pub(super) writer_task_begin_errors: AtomicU64,
554 pub(super) writer_task_request_failures: AtomicU64,
555 pub(super) writer_task_side_effects_unknown: AtomicU64,
556 pub(super) writer_guard_drop_rollbacks: AtomicU64,
557}
558
559impl<'pool> WriterGuard<'pool> {
560 pub(crate) fn admit_autocommit(self) -> Result<PooledAutocommitWriteUnit<'pool>, SqliteError> {
564 if !self.guard.is_autocommit() {
565 self.pool.retire_pooled_writer(&self.guard);
566 return Err(SqliteError::InvalidData(
567 "pooled autocommit write began on a connection in a transaction".to_string(),
568 ));
569 }
570 self.ensure_logical_write_checkout(
571 "checkpoint writer checkout cannot admit a logical write",
572 )?;
573 self.admission.check()?;
574 Ok(PooledAutocommitWriteUnit { writer: self })
575 }
576
577 fn ensure_logical_write_checkout(&self, message: &'static str) -> Result<(), SqliteError> {
578 if self._volume_lease.is_none()
579 && self.pool.canonical_path().is_some()
580 && !self.pool.config.read_only
581 {
582 return Err(SqliteError::InvalidData(message.to_string()));
583 }
584 Ok(())
585 }
586
587 pub(crate) fn conn(&self) -> &Connection {
589 &self.guard
590 }
591
592 pub(crate) fn conn_mut(&mut self) -> &mut Connection {
594 &mut self.guard
595 }
596
597 pub fn autocommit<R>(
621 self,
622 operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
623 ) -> Result<R, SqliteError> {
624 let unit = self.admit_autocommit()?;
625 let result = operation(unit.conn()).map_err(statement_error);
626 if unit.conn().is_autocommit() {
627 return result;
628 }
629 let rollback_proven = unit
630 .writer
631 .rollback_or_retire("autocommit script left its transaction open")
632 .is_ok();
633 settle_open_autocommit_result(
634 result,
635 rollback_proven,
636 "pooled script left a transaction open; rolled back",
637 )
638 }
639
640 #[cfg(any(test, feature = "test-support"))]
644 pub fn autocommit_sqlite<R>(
645 self,
646 operation: impl FnOnce(&Connection) -> rusqlite::Result<R>,
647 ) -> Result<R, SqliteError> {
648 self.autocommit(|conn| operation(conn).map_err(Into::into))
649 }
650
651 pub fn transaction<F, R>(self, f: F) -> Result<R, SqliteError>
661 where
662 F: FnOnce(&Connection) -> Result<R, SqliteError>,
663 {
664 let mut tx_handle = None;
665 let writer = self;
666 writer.ensure_logical_write_checkout(
667 "checkpoint writer checkout cannot start a logical transaction",
668 )?;
669 writer.begin_admitted_transaction()?;
670 let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
671 Some("writer_guard_tx".to_string()),
672 writer.origin.clone(),
673 ));
674
675 match f(&writer.guard) {
676 Ok(result) => {
677 if let Err(err) = writer.guard.execute_batch("COMMIT") {
678 if writer.rollback_or_retire("commit failure").is_err() {
679 return Err(SqliteError::settlement_with_cause(
680 &err,
681 khive_storage::error::SqliteWriteStage::Commit,
682 ));
683 }
684 return Err(SqliteError::write(
685 err,
686 khive_storage::error::SqliteWriteStage::Commit,
687 ));
688 }
689 if !writer.guard.is_autocommit() {
690 writer.pool.retire_pooled_writer(&writer.guard);
691 return Err(SqliteError::WriterSettlementUnknown);
692 }
693 Ok(result)
694 }
695 Err(err) => {
696 if writer
697 .rollback_or_retire("transaction body failure")
698 .is_err()
699 {
700 return Err(SqliteError::settlement_with_cause(
701 &err,
702 khive_storage::error::SqliteWriteStage::Statement,
703 ));
704 }
705 Err(match err {
706 SqliteError::Rusqlite(error) => {
707 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
708 }
709 other => other,
710 })
711 }
712 }
713 }
714
715 fn begin_admitted_transaction(&self) -> Result<(), SqliteError> {
717 if !self.guard.is_autocommit() {
718 self.pool.retire_pooled_writer(&self.guard);
719 return Err(SqliteError::InheritedWriterTransaction);
720 }
721 if let Err(error) = self.guard.execute_batch("BEGIN IMMEDIATE") {
722 if !self.guard.is_autocommit() {
723 self.pool.retire_pooled_writer(&self.guard);
724 return Err(SqliteError::settlement_with_cause(
725 &error,
726 khive_storage::error::SqliteWriteStage::Begin,
727 ));
728 }
729 return Err(SqliteError::write(
730 error,
731 khive_storage::error::SqliteWriteStage::Begin,
732 ));
733 }
734 if let Err(error) = self.admission.check() {
735 self.rollback_or_retire("capacity admission")?;
736 return Err(error);
737 }
738 Ok(())
739 }
740
741 pub(crate) fn rollback_or_retire(&self, context: &str) -> Result<(), SqliteError> {
742 if !crate::connection_settlement::rollback_proves_autocommit(&self.guard) {
743 self.pool.retire_pooled_writer(&self.guard);
744 tracing::error!(context, "pooled writer rollback did not prove autocommit");
745 return Err(SqliteError::WriterSettlementUnknown);
746 }
747 Ok(())
748 }
749}
750
751pub(crate) struct PooledMigrationTransactions<'pool> {
753 pool: &'pool ConnectionPool,
754}
755
756impl crate::migrations::MigrationTransactions for PooledMigrationTransactions<'_> {
757 fn admitted<T>(
758 &mut self,
759 operation: impl FnOnce(&mut Connection) -> Result<T, SqliteError>,
760 ) -> Result<T, SqliteError> {
761 let mut writer = self.pool.writer()?;
762 let result = operation(writer.conn_mut());
763 if writer.guard.is_autocommit() {
764 return result;
765 }
766 writer.rollback_or_retire("schema migration left its transaction open")?;
767 result.and(Err(SqliteError::WriterSettlementUnknown))
769 }
770}
771
772impl Drop for WriterGuard<'_> {
773 fn drop(&mut self) {
774 if !self.guard.is_autocommit() {
775 let settlement = self.rollback_or_retire("guard dropped with open transaction");
779 self.pool.record_writer_guard_drop(&settlement);
780 }
781 if self.pool.pooled_writer_retired.load(Ordering::Acquire) {
782 if let Some(replacement) = self.pool.retirement_connection.lock().take() {
783 let original = std::mem::replace(&mut *self.guard, replacement);
785 let _ = self.admission.close_retired_connection(original);
786 }
787 }
788 }
789}
790
791impl ConnectionPool {
792 #[track_caller]
808 pub fn standalone_autocommit<R>(
809 &self,
810 operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
811 ) -> Result<R, SqliteError> {
812 let unit = self.standalone_write_unit()?;
813 self.write_admission.check()?;
814 let result = operation(unit.conn()).map_err(statement_error);
815 if unit.conn().is_autocommit() {
816 return result;
817 }
818 let rollback_proven = crate::connection_settlement::rollback_proves_autocommit(unit.conn());
819 settle_open_autocommit_result(
820 result,
821 rollback_proven,
822 "standalone script left a transaction open; rolled back",
823 )
824 }
825
826 #[track_caller]
833 pub fn standalone_transaction<R>(
834 &self,
835 operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
836 ) -> Result<R, SqliteError> {
837 let mut tx_handle = None;
838 let unit = self.standalone_transaction_write_unit()?;
839 let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
840 Some("standalone_transaction".into()),
841 self.origin(),
842 ));
843 match operation(unit.conn()).map_err(statement_error) {
844 Ok(value) => match unit.conn().execute_batch("COMMIT") {
845 Ok(()) if unit.conn().is_autocommit() => Ok(value),
846 Ok(()) => Err(SqliteError::WriterSettlementUnknown),
847 Err(error) => {
848 if unit.conn().execute_batch("ROLLBACK").is_err()
849 || !unit.conn().is_autocommit()
850 {
851 return Err(SqliteError::settlement_with_cause(
852 &error,
853 khive_storage::error::SqliteWriteStage::Commit,
854 ));
855 }
856 Err(SqliteError::write(
857 error,
858 khive_storage::error::SqliteWriteStage::Commit,
859 ))
860 }
861 },
862 Err(error) => {
863 if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
864 return Err(SqliteError::settlement_with_cause(
865 &error,
866 khive_storage::error::SqliteWriteStage::Statement,
867 ));
868 }
869 Err(error)
870 }
871 }
872 }
873
874 #[track_caller]
875 pub(crate) fn autocommit_write_unit(
876 &self,
877 ) -> Result<PooledAutocommitWriteUnit<'_>, SqliteError> {
878 self.writer()?.admit_autocommit()
879 }
880
881 #[track_caller]
882 pub(crate) fn transaction_write_unit(
883 &self,
884 ) -> Result<super::PooledTransactionWriteUnit<'_>, SqliteError> {
885 let writer = self.writer()?;
886 writer.begin_admitted_transaction()?;
887 Ok(PooledTransactionWriteUnit { writer })
888 }
889
890 #[track_caller]
895 pub(crate) fn execute_direct_transaction<R, F>(
896 &self,
897 capability: StorageCapability,
898 operation: &'static str,
899 f: F,
900 ) -> Result<R, StorageError>
901 where
902 F: FnOnce(&Connection) -> Result<R, StorageError>,
903 {
904 let _tx_handle =
905 khive_storage::tx_registry::register_scoped(Some(operation.to_string()), self.origin());
906 let db_label = crate::timeout_sink::db_label(self);
907 let map_admission_error = |error: SqliteError| {
908 crate::timeout_sink::maybe_emit_sqlite_full(&db_label, &error);
909 let error = error.into_storage_error(capability, operation);
910 self.record_direct_writer_error(&error);
911 error
912 };
913 let result = if self.canonical_path().is_some() {
914 let unit = self
915 .standalone_transaction_write_unit()
916 .map_err(map_admission_error)?;
917 let (result, _) = execute_wrapped_transaction(unit.conn(), operation, f);
918 result
919 } else {
920 let unit = self.transaction_write_unit().map_err(map_admission_error)?;
921 let conn = unit.conn();
922 let (result, terminal_state) = execute_wrapped_transaction(conn, operation, f);
923 if terminal_state.is_some() {
924 self.retire_pooled_writer(conn);
925 }
926 result
927 };
928 if let Err(error) = &result {
929 crate::timeout_sink::maybe_emit_sqlite_full(&db_label, error);
930 self.record_direct_writer_error(error);
931 }
932 result
933 }
934
935 pub fn run_migrations(&self) -> Result<u32, SqliteError> {
938 if self.config.read_only {
939 return Err(SqliteError::InvalidData(
940 "cannot run migrations on a read-only pool".to_string(),
941 ));
942 }
943 let owner = crate::stores::blob::acquire_database_gc_owner_for_path_blocking(
944 self.canonical_path().map(Path::to_path_buf),
945 )
946 .map_err(|error| {
947 SqliteError::InvalidData(format!(
948 "failed to acquire database GC owner before schema migration: {error}"
949 ))
950 })?;
951 crate::migrations::run_migrations_with_database_gc_owner(
952 &mut self.migration_transactions(),
953 &owner,
954 &self.write_admission,
955 )
956 }
957
958 pub(crate) fn migration_transactions(&self) -> PooledMigrationTransactions<'_> {
962 PooledMigrationTransactions { pool: self }
963 }
964
965 #[track_caller]
969 pub(crate) fn standalone_transaction_write_unit(
970 &self,
971 ) -> Result<super::StandaloneWriteUnit, SqliteError> {
972 let unit = self.standalone_write_unit()?;
973 self.begin_standalone_transaction(unit)
974 }
975
976 #[track_caller]
979 pub(crate) fn standalone_sql_bridge_transaction_write_unit(
980 &self,
981 ) -> Result<super::StandaloneWriteUnit, StorageError> {
982 let unit = self
983 .standalone_write_unit()
984 .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
985 for (name, value) in [
986 ("cache_size", sqlite_cache_size_pragma()),
987 ("mmap_size", sqlite_mmap_size_pragma()),
988 ] {
989 unit.conn()
990 .pragma_update(None, name, value)
991 .map_err(|error| {
992 StorageError::driver(StorageCapability::Sql, "open_writer", error)
993 })?;
994 }
995 self.begin_standalone_transaction(unit)
996 .map_err(|error| match error {
997 SqliteError::Write { stage, source } => {
998 crate::timeout_sink::maybe_emit_busy(
999 &crate::timeout_sink::db_label(self),
1000 crate::timeout_sink::Site::StandaloneSqlBridge,
1001 &source,
1002 );
1003 crate::error::with_write_stage(
1004 StorageError::driver(StorageCapability::Sql, "execute", source),
1005 stage,
1006 )
1007 }
1008 SqliteError::Rusqlite(source) => {
1009 crate::timeout_sink::maybe_emit_busy(
1010 &crate::timeout_sink::db_label(self),
1011 crate::timeout_sink::Site::StandaloneSqlBridge,
1012 &source,
1013 );
1014 StorageError::driver(StorageCapability::Sql, "execute", source)
1015 }
1016 error => error.into_storage_error(StorageCapability::Sql, "execute"),
1017 })
1018 }
1019
1020 fn begin_standalone_transaction(
1021 &self,
1022 unit: StandaloneWriteUnit,
1023 ) -> Result<StandaloneWriteUnit, SqliteError> {
1024 if let Err(error) = unit.conn().execute_batch("BEGIN IMMEDIATE") {
1025 if !unit.conn().is_autocommit() {
1026 return Err(SqliteError::settlement_with_cause(
1027 &error,
1028 khive_storage::error::SqliteWriteStage::Begin,
1029 ));
1030 }
1031 return Err(SqliteError::write(
1032 error,
1033 khive_storage::error::SqliteWriteStage::Begin,
1034 ));
1035 }
1036 if let Err(error) = self.write_admission.check() {
1037 if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
1038 return Err(SqliteError::WriterSettlementUnknown);
1039 }
1040 return Err(error);
1041 }
1042 Ok(unit)
1043 }
1044}
1045
1046fn settle_open_autocommit_result<R>(
1047 result: Result<R, SqliteError>,
1048 rollback_proven: bool,
1049 left_open_message: &'static str,
1050) -> Result<R, SqliteError> {
1051 match (rollback_proven, result) {
1052 (true, result) => result.and(Err(SqliteError::InvalidData(left_open_message.into()))),
1053 (false, Err(error)) => Err(SqliteError::settlement_with_cause(
1054 &error,
1055 khive_storage::error::SqliteWriteStage::Statement,
1056 )),
1057 (false, Ok(_)) => Err(SqliteError::WriterSettlementUnknown),
1058 }
1059}
1060
1061fn statement_error(error: SqliteError) -> SqliteError {
1062 match error {
1063 SqliteError::Rusqlite(error) => {
1064 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
1065 }
1066 other => other,
1067 }
1068}
1069
1070#[cfg(test)]
1071#[path = "standalone_write_tests.rs"]
1072mod standalone_write_tests;
1073
1074#[cfg(test)]
1075#[path = "pooled_write_tests.rs"]
1076mod pooled_write_tests;