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;