Skip to main content

khive_db/pool/
write_units.rs

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
12/// The SQLite write reserve is sampled at each operation admission. SQLite
13/// does not expose the size of an arbitrary upcoming transaction, so the
14/// reserve is a warning boundary, not a guarantee that a single very large
15/// transaction cannot consume more than the remaining headroom.
16pub(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    /// Set once a retired connection could neither roll back nor close: the
24    /// outcome of its transaction is unknown, so every later write is refused.
25    settlement_unknown: AtomicBool,
26    /// Lease waits that ran out `guard_deadline` because another writer held
27    /// the volume. Read through [`WriterAcquisitionSnapshot::lease_timeouts`].
28    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    /// Build admission for a raw connection with no backend-local override.
69    /// Pooled callers must use their pool's effective policy instead.
70    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    /// Settle a retired connection while the caller still holds its lease. A
123    /// terminal failure returns the typed outcome-unknown error for this write
124    /// and poisons this admission, so every later write on the pool, the
125    /// writer task and standalone writers is refused before it starts; the
126    /// caller may then release its lease.
127    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        // SQL does not tell admission how many bytes a generic transaction
199        // will append. VACUUM supplies its known copy-sized estimate here.
200        // A zero reserve removes the floor term only: an operation-specific
201        // headroom is still compared, and with neither term nothing is.
202        // Overflow is a refusal, never a wrapped low threshold.
203        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    /// Acquire the physical-volume lease before SQLite writer acquisition.
218    /// The caller must retain the returned guard through settlement. A request
219    /// from a thread that already holds this volume's lease fails at once as
220    /// re-entry, naming both call sites, instead of waiting out the deadline.
221    #[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    /// The lease is taken before the pool mutex, so ordinary same-volume
246    /// writer contention ends here rather than at `checkout_timeout`. Count it
247    /// and write a `timeout` row with `phase=lock_contended`, as the pool mutex stage
248    /// does for its own timeouts, so the contention stays visible.
249    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    /// Admission for VACUUM: its copy-sized headroom is compared even under a
268    /// zero reserve, and a headroom that cannot be estimated refuses the
269    /// operation instead of admitting it with none.
270    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
299/// A writer connection checked out from the pool.
300/// The Mutex ensures only one writer at a time.
301///
302/// Checkout retains exclusion; each consuming operation samples capacity at
303/// its execution boundary. Raw connection access is not a public capability:
304/// ```compile_fail
305/// use khive_db::ConnectionPool;
306/// fn raw(pool: &ConnectionPool) {
307///     let writer = pool.writer().unwrap();
308///     let _connection = writer.conn();
309/// }
310/// ```
311/// ```compile_fail
312/// use khive_db::ConnectionPool;
313/// fn raw_mut(pool: &ConnectionPool) {
314///     let mut writer = pool.writer().unwrap();
315///     let _connection = writer.conn_mut();
316/// }
317/// ```
318/// ```compile_fail
319/// use khive_db::ConnectionPool;
320/// fn raw_mut(pool: &ConnectionPool) {
321///     let mut writer = pool.writer().unwrap();
322///     let _connection: &mut rusqlite::Connection = &mut *writer;
323/// }
324/// ```
325///
326/// # Terminal settlement
327/// Dropping a retired writer settles its connection before the volume lease is
328/// released. If cleanup cannot restore autocommit and owned SQLite close also
329/// fails, the database path, volume, and errors are emitted to stderr and
330/// tracing, that write reports [`SqliteError::WriterSettlementUnknown`], the
331/// pool is poisoned so every later write is refused with
332/// [`SqliteError::WriterPoisoned`] before it starts, and the lease is then
333/// released.
334pub struct WriterGuard<'pool> {
335    pub(super) guard: parking_lot::MutexGuard<'pool, Connection>,
336    /// The origin (ADR-091 backend-scoped attribution) of the pool this
337    /// guard was checked out from, carried so `transaction` can register its
338    /// span with the correct origin without holding a `&ConnectionPool`.
339    pub(super) origin: TxOrigin,
340    pub(super) pool: &'pool ConnectionPool,
341    pub(super) admission: &'pool WriteAdmission,
342    /// Normal writer checkout acquires this before taking the writer mutex.
343    /// Maintenance-only nowait checkout leaves it absent to bypass the floor.
344    pub(super) _volume_lease: Option<VolumeLease>,
345}
346
347/// One synchronous pooled autocommit write or script. Construction samples
348/// capacity under the volume lease, and the owned writer guard retains that
349/// lease until this unit is dropped after SQLite returns to autocommit.
350pub(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
364/// One pooled transaction after lease, BEGIN, and capacity admission. The
365/// owned writer guard rolls back on drop if the caller fails to settle it.
366pub(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
376/// One standalone write unit on an owned connection. Settlement (autocommit
377/// or successful owned close) precedes release of the volume lease, including
378/// when the operation unwinds or its initial rollback fails.
379pub(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            // A terminal failure has poisoned the admission; Drop cannot
415            // return it, and the lease is released after this returns.
416            let _ = self.admission.close_retired_connection(conn);
417        }
418    }
419}
420
421/// A zero-wait checkout that can run only the fixed checkpoint recovery
422/// pragmas. The connection remains private: exposing it would let a caller
423/// execute logical writes without disk-reserve admission (ADR-154 §5).
424///
425/// Ordinary SQL is deliberately unavailable through this capability:
426/// ```compile_fail
427/// use khive_db::{ConnectionPool, PoolConfig};
428/// let pool = ConnectionPool::new(PoolConfig::default()).unwrap();
429/// pool.try_checkpoint_nowait().unwrap().execute_batch("CREATE TABLE bypass (id INTEGER)");
430/// ```
431pub struct CheckpointGuard<'pool> {
432    pub(super) guard: parking_lot::MutexGuard<'pool, Connection>,
433}
434
435/// SQLite's three-column result from a fixed WAL checkpoint pragma.
436#[derive(Debug, Clone, Copy, PartialEq, Eq)]
437pub struct CheckpointResult {
438    /// Whether SQLite reported a busy checkpoint.
439    pub busy: i64,
440    /// WAL frames observed by SQLite (`-1` when there is no WAL).
441    pub log_frames: i64,
442    /// WAL frames copied back into the database.
443    pub checkpointed_frames: i64,
444}
445
446impl CheckpointGuard<'_> {
447    /// Run a PASSIVE checkpoint without disk-reserve admission.
448    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    /// Run a TRUNCATE checkpoint without disk-reserve admission.
461    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/// Process-local monotonic counters for every instrumented writer acquisition
475/// boundary owned by one [`ConnectionPool`].
476///
477/// The aggregate `acquisitions` is the saturating sum of its three explicit
478/// connection classes. Infrastructure-only opens (the diagnostics PASSIVE
479/// probe, the writer task's one-time lifetime connection, and the checkpoint
480/// task's dedicated long-lived connection) are excluded; zero-wait
481/// maintenance probes also remain outside these request-traffic counters.
482#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
483pub struct WriterAcquisitionSnapshot {
484    /// Successful acquisitions across pooled, standalone, and writer-task
485    /// connection classes.
486    pub acquisitions: u64,
487    /// Successful finite-wait pool-mutex writer checkouts.
488    pub pooled_acquisitions: u64,
489    /// Successful per-operation standalone writer connection opens.
490    pub standalone_acquisitions: u64,
491    /// Successful writer-task ownership acquisitions (one per dequeued
492    /// top-level request or successful `BEGIN IMMEDIATE`).
493    pub writer_task_acquisitions: u64,
494    /// Finite-wait pool writer checkouts that exhausted `checkout_timeout`
495    /// waiting for the pool mutex. A file-backed writer reaches that wait only
496    /// after it holds the volume lease; a wait that ends at the lease is
497    /// counted in `lease_timeouts` instead.
498    pub timeouts: u64,
499    /// Writer acquisitions refused because another writer held the volume
500    /// lease past `disk_guard_deadline_ms`, returned as
501    /// `CapacityUnavailable { phase: Lock }`. Every write path takes the lease
502    /// before its connection, so same-volume writer contention is counted
503    /// here, across all of this pool's writer classes.
504    pub lease_timeouts: u64,
505    /// Instrumented direct executions whose final returned error retains SQLite's
506    /// primary DatabaseBusy code, once per operation after its busy handler.
507    /// Excludes LOCKED, checkout/open/admission failures, readers, writer tasks,
508    /// infrastructure probes and uninstrumented raw connection escapes.
509    pub direct_busy_refusals: u64,
510    /// Every writer-task `BEGIN IMMEDIATE` attempt refused busy or locked,
511    /// including refusals a subsequent bounded retry went on to absorb.
512    /// Counted separately from `timeouts` because that counter names the
513    /// pool-mutex checkout stage; folding the two would mislabel the stage.
514    pub writer_task_begin_busy: u64,
515    /// Subset of `writer_task_begin_busy` that a subsequent bounded retry
516    /// absorbed before the request closure ran, so the refusal never
517    /// reached the caller. `writer_task_begin_busy - writer_task_begin_busy_absorbed`
518    /// is the count of refusals a caller actually observed.
519    pub writer_task_begin_busy_absorbed: u64,
520    /// Writer-task `BEGIN IMMEDIATE` attempts that failed for a reason other
521    /// than busy or locked, and so surface as `StorageError::Pool`.
522    pub writer_task_begin_errors: u64,
523    /// Dequeued writer-task requests that reached the writer seam (executed
524    /// or attempted to execute their operation) and terminated in error,
525    /// counted once per request regardless of the specific terminal state.
526    pub writer_task_request_failures: u64,
527    /// Subset of `writer_task_request_failures` whose terminal state was
528    /// `WriterTaskRequestState::SideEffectsUnknown` — the commit or rollback
529    /// outcome could not be established, so the request's side effects on
530    /// the database are unknown.
531    pub writer_task_side_effects_unknown: u64,
532    /// Pooled writer guards released while their connection was still inside
533    /// a transaction, which the guard's drop then rolled back (or, when the
534    /// rollback could not prove autocommit, retired). Every writer path settles
535    /// its transaction before releasing the guard, so a non-zero count is a
536    /// caller that left one open; each drop also writes a `writer_guard_drop`
537    /// row to the timeout sink.
538    pub writer_guard_drop_rollbacks: u64,
539}
540
541/// Atomics backing [`WriterAcquisitionSnapshot`]. The writer task retains an
542/// `Arc` after spawn so its per-request acquisition site can update the same
543/// pool-scoped snapshot without retaining the whole pool.
544#[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    /// Bind the lease already owned by this guard to one autocommit write
561    /// unit. The caller must construct the unit immediately before its first
562    /// SQLite write, then keep it through the last call in that unit.
563    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    /// Borrow inside an already owned internal write boundary.
588    pub(crate) fn conn(&self) -> &Connection {
589        &self.guard
590    }
591
592    /// Borrow for the internal migration owner that retains this guard.
593    pub(crate) fn conn_mut(&mut self) -> &mut Connection {
594        &mut self.guard
595    }
596
597    /// Own one autocommit operation or complete SQL script.
598    ///
599    /// Capacity is checked immediately before the callback. A script must
600    /// finish every transaction it starts; an unfinished one is rolled back
601    /// and refused. The consumed guard retains its lease through settlement,
602    /// including if the callback unwinds.
603    ///
604    /// ```no_run
605    /// use khive_db::{ConnectionPool, SqliteError};
606    /// fn seed(pool: &ConnectionPool) -> Result<(), SqliteError> {
607    ///     pool.writer()?.autocommit(|conn| {
608    ///         conn.execute_batch("CREATE TABLE example(value INTEGER)")?;
609    ///         Ok(())
610    ///     })
611    /// }
612    /// ```
613    /// The callback cannot return a connection borrow:
614    /// ```compile_fail
615    /// use khive_db::ConnectionPool;
616    /// fn escape(pool: &ConnectionPool) {
617    ///     let _connection = pool.writer().unwrap().autocommit(|conn| Ok(conn));
618    /// }
619    /// ```
620    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    /// Run a native SQLite fixture operation through the usual autocommit owner.
641    ///
642    /// Available only to test builds and dependents enabling `test-support`.
643    #[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    /// Execute a write transaction.
652    /// Consumes this guard through BEGIN IMMEDIATE, post-BEGIN admission and
653    /// COMMIT/ROLLBACK. The callback must not settle the outer transaction itself.
654    ///
655    /// # Panics
656    ///
657    /// A callback panic propagates to the caller. During unwinding, this guard
658    /// attempts rollback or retirement before releasing its volume lease and
659    /// registered transaction evidence.
660    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    /// Acquire SQLite's writer slot before sampling logical-write capacity.
716    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
751/// See [`ConnectionPool::migration_transactions`].
752pub(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        // Rolled back: an operation that reported success did not commit.
768        result.and(Err(SqliteError::WriterSettlementUnknown))
769    }
770}
771
772impl Drop for WriterGuard<'_> {
773    fn drop(&mut self) {
774        if !self.guard.is_autocommit() {
775            // Last-resort settlement: the writer that opened this transaction
776            // returned without settling it. Its caller has already been
777            // answered, so the outcome is recorded rather than returned.
778            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                // The mutex excludes all aliases; settlement precedes lease release.
784                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    /// Run one standalone autocommit operation or complete SQL script.
793    ///
794    /// The connection and volume lease remain owned by this call. Capacity
795    /// is checked immediately before the callback. A script may contain
796    /// complete transactions, but returning with a transaction still open
797    /// rolls it back and reports an error. Use [`Self::standalone_transaction`]
798    /// when this API should own BEGIN IMMEDIATE and COMMIT instead.
799    ///
800    /// The callback cannot return a connection borrow:
801    /// ```compile_fail
802    /// use khive_db::ConnectionPool;
803    /// fn escape(pool: &ConnectionPool) {
804    ///     let _connection = pool.standalone_autocommit(|conn| Ok(conn));
805    /// }
806    /// ```
807    #[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    /// Run a standalone BEGIN IMMEDIATE transaction under the volume lease.
827    ///
828    /// Capacity is sampled after BEGIN succeeds and before the callback.
829    /// This call owns COMMIT/ROLLBACK; the callback must not settle the outer
830    /// transaction itself. A panic drops the owned connection before the
831    /// lease can be released.
832    #[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    /// Execute DML on a typed direct transaction, choosing the standalone
891    /// connection required by file-backed async stores or the pooled writer
892    /// used by in-memory stores. The callback cannot begin or commit its own
893    /// outer transaction; this seam owns settlement and the volume lease.
894    #[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    /// Run core migrations while preserving owner-before-lease-before-writer
936    /// order for callers that hold a pool but not a backend wrapper.
937    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    /// Migration writes through this pool's writer, checked out in
959    /// lease-then-writer order for each admitted unit and returned once that
960    /// unit has settled.
961    pub(crate) fn migration_transactions(&self) -> PooledMigrationTransactions<'_> {
962        PooledMigrationTransactions { pool: self }
963    }
964
965    /// Own one standalone write transaction from lease acquisition through
966    /// settlement. The free-space sample occurs only after BEGIN IMMEDIATE
967    /// has acquired SQLite's writer slot.
968    #[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    /// The SQL bridge's complete standalone transaction owner. Configure the
977    /// connection before BEGIN, then retain its lease through settlement.
978    #[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;