Skip to main content

sqlive/
database.rs

1//! A database's connections: one writer, the readers beside it, and the
2//! upkeep threads that checkpoint its WAL and keep its planner's statistics.
3//! No connection leaves it: the host runs its SQL through `host` on the
4//! writer and through a `Reader` on a reader.
5
6#[path = "read_pool.rs"]
7mod read_pool;
8
9use crate::authorization::{Policy, PolicyError};
10use crate::connection::HostSql;
11use crate::connection_setup::Setup;
12use crate::planner_statistics::PlannerStatistics;
13use crate::upkeep::UpkeepThread;
14use crate::wal_checkpoints::WalCheckpointer;
15use panic_as_error::locks::{into_unpoisoned, lock_unpoisoned};
16use std::collections::BTreeSet;
17use std::num::{NonZeroU32, NonZeroUsize};
18use std::path::Path;
19use std::sync::{Arc, Mutex};
20use tokio::sync::watch;
21
22pub use read_pool::Reader;
23
24/// How to open a database's connections. Every connection gets a policy of
25/// its own from `policy`, and the same `setup`.
26pub struct Options<'a, P: Policy> {
27    /// The SQLite settings of every connection.
28    pub settings: crate::SqliteSettings,
29    /// The read-only connections beside the writer.
30    pub readers: NonZeroUsize,
31    /// Run `prepare` on the first reader, and open the writer only once
32    /// `prepare` passes, leaving the journal mode as it is. Set this for a
33    /// database whose checks must not write, because its writer would create
34    /// the file or the schema the checks look for. Otherwise the writer
35    /// switches the database to WAL and runs `prepare`.
36    pub prepare_on_reader: bool,
37    /// The views and tables a live query reads whole.
38    pub whole_views: Arc<crate::WholeViews>,
39    /// Each connection's policy, made as the connection opens.
40    pub policy: &'a dyn Fn() -> P,
41    /// What each connection registers, given that connection's policy,
42    /// before any SQL runs on it.
43    pub setup: &'a dyn Fn(&Setup<'_, P>, &P) -> rusqlite::Result<()>,
44    /// Capture the writer's commits for the handle's live queries, and record
45    /// each operation of a write on these tables, named in lowercase, with
46    /// every column's value before and after it.
47    pub capture: Option<BTreeSet<String>>,
48    /// Checkpoint the WAL on a thread of its own once it holds this many
49    /// frames not yet in the database file (§4).
50    pub checkpoint_pages: Option<NonZeroU32>,
51    /// Gather the planner's statistics as the database opens, keep them on
52    /// a thread of their own while it stays open, and gather them again as
53    /// it closes (§4).
54    pub statistics: bool,
55}
56
57/// One database's connections and upkeep threads.
58pub struct Database<P: Policy> {
59    /// Shared with the upkeep threads, which hold it while they run.
60    writer: Arc<Mutex<HostSql<P>>>,
61    readers: read_pool::ReadPool<P>,
62    /// The handle the connections serve.
63    handle: crate::Handle<P::Failure>,
64    checkpoints: Option<WalCheckpointer<P>>,
65    statistics: Option<UpkeepThread<PlannerStatistics<P>>>,
66    /// The main file's size after the latest checkpoint. The database keeps
67    /// this receiver unread, so each view it hands out sees every change
68    /// since the open.
69    checkpointed_size: watch::Receiver<u64>,
70}
71
72impl<P: Policy> Database<P> {
73    /// Open the database at `path`: its writer, switched to WAL, then
74    /// `prepare` on the writer (or on the first reader, as `options` asks)
75    /// before the database serves anything; then the statistics, commit
76    /// capture, upkeep threads and readers `options` asks for. Every
77    /// connection then serves `handle`, which their failures fail.
78    pub fn open_with<T, E: From<PolicyError<P>>>(
79        path: &Path,
80        handle: crate::Handle<P::Failure>,
81        options: Options<'_, P>,
82        prepare: impl FnOnce(&mut HostSql<P>) -> Result<T, E>,
83    ) -> Result<(Self, T), E> {
84        // Every connection orders its commits and snapshots with the others
85        // (`snapshot_values.rs`).
86        let order = Arc::new(crate::snapshot_values::CommitOrder::new());
87        let open = |read_only| {
88            let mut connection = HostSql::open(
89                path,
90                read_only,
91                (options.policy)(),
92                Arc::clone(&options.whole_views),
93                &options.settings,
94                options.setup,
95            )?;
96            connection.share_commit_order(Arc::clone(&order));
97            Ok::<_, PolicyError<P>>(connection)
98        };
99        // The watch starts at the main file's size as the writer opens. The
100        // writer holds the watch from then on, so the watch gets the size
101        // after each checkpoint the open runs; the checkpointer holds it too
102        // once it starts.
103        let open_writer = || -> Result<(HostSql<P>, watch::Sender<u64>), PolicyError<P>> {
104            let mut writer = open(false)?;
105            let sizes = watch::Sender::new(writer.database_file_size()?);
106            writer.send_checkpointed_sizes(sizes.clone());
107            Ok((writer, sizes))
108        };
109        let statistics = options.statistics;
110        let mut readers = Vec::with_capacity(options.readers.get());
111        let (mut writer, sizes, prepared) = if options.prepare_on_reader {
112            assert!(!statistics, "a database prepared on a reader gathers no statistics");
113            let mut first = open(true)?;
114            let prepared = first.with_profile(prepare)?;
115            readers.push(first);
116            let (writer, sizes) = open_writer()?;
117            (writer, sizes, prepared)
118        } else {
119            let (mut writer, sizes) = open_writer()?;
120            let prepared = writer.with_profile(|writer| -> Result<T, E> {
121                writer.enable_wal()?;
122                let prepared = prepare(writer)?;
123                if statistics {
124                    // On a connection of its own: one that analyzes a small
125                    // table loads its count, and forgetting the statistics
126                    // afterwards doesn't unload it. The writer then reads
127                    // what that connection kept; SQLite reads its statistics
128                    // again only when told to.
129                    open(false)?.gather_statistics()?;
130                    writer.batch("ANALYZE sqlite_schema")?;
131                }
132                Ok(prepared)
133            })?;
134            (writer, sizes, prepared)
135        };
136        // Switching a new database to WAL writes the main file's first page,
137        // and the commits `open_with` ran so far may have run SQLite's own
138        // automatic checkpoint, which sends no size. So the writer sends the
139        // file's size here, and no commit runs between this send and the
140        // checkpointer's start.
141        writer.send_checkpointed_size()?;
142        match options.capture {
143            Some(recorded) => writer.observe_commits(handle.clone(), recorded),
144            None => writer.serve(handle.clone()),
145        }
146        let mut database = Self {
147            writer: Arc::new(Mutex::new(writer)),
148            readers: read_pool::ReadPool::new(Vec::new()),
149            handle: handle.clone(),
150            checkpoints: None,
151            statistics: None,
152            checkpointed_size: sizes.subscribe(),
153        };
154        // Each upkeep thread stops as `database` drops, should a later step
155        // fail.
156        if let Some(pages) = options.checkpoint_pages {
157            let mut checkpointer = open(false)?;
158            checkpointer.send_checkpointed_sizes(sizes);
159            database.checkpoints = Some(WalCheckpointer::start(
160                checkpointer,
161                &database.writer,
162                pages,
163                handle.clone(),
164            )?);
165        }
166        if statistics {
167            let connection = open(false)?;
168            // A run's commit holds the writer, so it must not checkpoint
169            // either.
170            if database.checkpoints.is_some() {
171                crate::wal_checkpoints::leave_checkpoints_to_checkpointer(&connection)?;
172            }
173            database.statistics = Some(UpkeepThread::<PlannerStatistics<P>>::start(
174                connection,
175                &database.writer,
176                handle.clone(),
177            )?);
178        }
179        while readers.len() < options.readers.get() {
180            readers.push(open(true)?);
181        }
182        for reader in &mut readers {
183            reader.serve(handle.clone());
184        }
185        database.readers = read_pool::ReadPool::new(readers.into_iter().map(Mutex::new).collect());
186        Ok((database, prepared))
187    }
188
189    /// Run `run` on the writer, once no other call holds it.
190    pub fn host<T>(&self, run: impl FnOnce(&mut HostSql<P>) -> T) -> T {
191        with_locked(&self.writer, run)
192    }
193
194    /// An idle reader, once one is free; it stays the caller's until the
195    /// lease drops.
196    pub fn reader(&self) -> Reader<'_, P> {
197        self.readers.acquire_reader()
198    }
199
200    /// A view of the main database file's size in bytes after the latest
201    /// checkpoint, which wakes when a later checkpoint changes the size.
202    /// Before the first checkpoint, the watch holds the file's size once the
203    /// commits `open_with` ran ended. The writer and the checkpointer send the
204    /// size after each checkpoint they run through
205    /// `HostSql::wal_checkpoint`: the checkpointer's own, and the host's on
206    /// the writer.
207    ///
208    /// Two kinds of checkpoint send nothing. SQLite checkpoints the WAL as
209    /// the database closes, and nothing reads the watch after that, because
210    /// the watch closes with the database. SQLite's own automatic
211    /// checkpoint, which runs inside a commit, sends nothing either; while
212    /// sqlive's checkpointer runs, no connection of the database's runs one.
213    /// Without the checkpointer, the writer runs one as its
214    /// `wal_autocheckpoint` asks.
215    pub fn checkpointed_size(&self) -> crate::CheckpointedSize {
216        crate::CheckpointedSize::new(self.checkpointed_size.clone())
217    }
218
219    /// Stop the upkeep threads; gather the planner's statistics again if
220    /// the database keeps them and its handle hasn't failed; then close every
221    /// connection. Closing goes on past each failure, and returns them all.
222    pub fn close(self) -> Vec<PolicyError<P>> {
223        let mut failures = Vec::new();
224        if let Some(checkpoints) = self.checkpoints {
225            failures.extend(checkpoints.stop().err());
226        }
227        if let Some(statistics) = self.statistics {
228            failures.extend(statistics.stop().err());
229            // The statistics follow this session's writes, outside any
230            // captured transaction. A failed handle's writer may still hold
231            // a transaction, which closing rolls back; a handle its host
232            // closed first leaves none.
233            if !self.handle.has_failed() {
234                failures.extend(lock_unpoisoned(&self.writer).optimize().err());
235            }
236        }
237        failures.extend(self.readers.close());
238        // Each upkeep thread stopped before, and let go of the writer.
239        match Arc::try_unwrap(self.writer) {
240            Ok(writer) => failures.extend(into_unpoisoned(writer).close().err()),
241            Err(_held) => failures.push(crate::Error::Invariant {
242                what: "a writer closes after its upkeep threads stopped",
243            }),
244        }
245        failures
246    }
247}
248
249/// Run `run` on `connection`, one of a database's connections. A panic while
250/// a caller holds the connection leaves it usable: its open transaction rolls
251/// back as the panic unwinds (`write_transaction.rs`), and a failed rollback
252/// fails the handle. So `with_locked` takes the lock even when a panic
253/// poisoned it.
254pub(crate) fn with_locked<T, R>(connection: &Mutex<T>, run: impl FnOnce(&mut T) -> R) -> R {
255    run(&mut lock_unpoisoned(connection))
256}
257
258#[cfg(any(test, feature = "test-utils"))]
259#[path = "database_test_hooks.rs"]
260mod test_hooks;