Skip to main content

khive_db/pool/
standalone_checkpoint.rs

1//! Owned checkpoint capabilities with no ordinary SQL interface.
2
3use rusqlite::Connection;
4
5use super::{CheckpointResult, ConnectionPool};
6use crate::checkpoint::{CheckpointConfig, CheckpointCoreOutcome, TruncateState};
7
8/// The dedicated checkpoint task's opened file. Only fixed recovery
9/// operations leave this module; its native connection cannot escape.
10pub(crate) struct CheckpointFile {
11    conn: Connection,
12}
13
14impl CheckpointFile {
15    pub(super) fn new(conn: Connection) -> Self {
16        if let Err(error) = conn.pragma_update(None, "wal_autocheckpoint", 0) {
17            tracing::warn!(target: "khive_db::checkpoint", %error,
18                "could not disable autocheckpoint on the dedicated checkpoint connection");
19        }
20        Self { conn }
21    }
22
23    pub(crate) fn run_core(
24        &self,
25        pool: &ConnectionPool,
26        config: &CheckpointConfig,
27        state: &mut TruncateState,
28    ) -> Result<CheckpointCoreOutcome, rusqlite::Error> {
29        crate::checkpoint::checkpoint_once_core(pool, &self.conn, config, state)
30    }
31
32    pub(crate) fn run(
33        &self,
34        pool: &ConnectionPool,
35        config: &CheckpointConfig,
36        state: &mut TruncateState,
37    ) -> Result<u64, rusqlite::Error> {
38        crate::checkpoint::checkpoint_once(pool, &self.conn, config, state)
39    }
40
41    fn checkpoint(&self, sql: &str) -> Result<CheckpointResult, rusqlite::Error> {
42        self.conn.query_row(sql, [], |row| {
43            Ok(CheckpointResult {
44                busy: row.get(0)?,
45                log_frames: row.get(1)?,
46                checkpointed_frames: row.get(2)?,
47            })
48        })
49    }
50
51    #[cfg(test)]
52    pub(crate) fn wal_autocheckpoint_pages_for_test(&self) -> rusqlite::Result<u32> {
53        self.conn
54            .query_row("PRAGMA wal_autocheckpoint", [], |row| row.get(0))
55    }
56
57    #[cfg(test)]
58    pub(crate) fn truncate_requests_attribution_for_test(
59        &self,
60        pool: &ConnectionPool,
61        config: &CheckpointConfig,
62        wal_pages_before: u64,
63        state: &mut TruncateState,
64    ) -> bool {
65        crate::checkpoint::truncate_requests_attribution_for_test(
66            pool,
67            &self.conn,
68            config,
69            wal_pages_before,
70            state,
71        )
72    }
73}
74
75/// A retained standalone connection restricted to WAL checkpoints.
76///
77/// It remains available below the logical-write reserve. It cannot issue
78/// arbitrary SQL or lend its connection to a caller:
79/// ```compile_fail
80/// use khive_db::ConnectionPool;
81/// fn bypass(pool: &ConnectionPool) {
82///     pool.open_standalone_checkpoint().unwrap()
83///         .execute_batch("CREATE TABLE bypass(value INTEGER)");
84/// }
85/// ```
86pub struct StandaloneCheckpoint<'pool> {
87    pool: &'pool ConnectionPool,
88    file: CheckpointFile,
89}
90
91impl<'pool> StandaloneCheckpoint<'pool> {
92    pub(super) fn new(pool: &'pool ConnectionPool, file: CheckpointFile) -> Self {
93        Self { pool, file }
94    }
95
96    /// Run the configured checkpoint cycle and update this pool's metrics.
97    pub fn run(
98        &self,
99        config: &CheckpointConfig,
100        state: &mut TruncateState,
101    ) -> Result<u64, rusqlite::Error> {
102        self.file.run(self.pool, config, state)
103    }
104
105    /// Run the fixed PASSIVE checkpoint without logical-write admission.
106    pub fn passive(&self) -> Result<CheckpointResult, rusqlite::Error> {
107        self.file.checkpoint("PRAGMA wal_checkpoint(PASSIVE)")
108    }
109
110    /// Run the fixed TRUNCATE checkpoint without logical-write admission.
111    pub fn truncate(&self) -> Result<CheckpointResult, rusqlite::Error> {
112        self.file.checkpoint("PRAGMA wal_checkpoint(TRUNCATE)")
113    }
114}