wabot-feature-sqlite 0.2.0

SQLite foundation for Wabot — the document store, migrations and connection handling, for a single-node deployment with no database server.
Documentation
//! Where the database lives and how it is tuned.
//!
//! The defaults are chosen for the deployment this crate exists for:
//! one node, one process, as little resident memory as the workload
//! allows. They are not the defaults a benchmark would pick.

use std::path::PathBuf;
use std::time::Duration;

use crate::error::{SqliteError, SqliteResult};

/// Connection settings.
#[derive(Debug, Clone)]
pub struct SqliteConfig {
    /// File path, or [`SqliteConfig::in_memory`] for a private
    /// database that vanishes with the process.
    pub path: Option<PathBuf>,
    /// How many concurrent readers to keep open.
    ///
    /// There is exactly **one** writer regardless — SQLite allows no
    /// more, and pretending otherwise is what turns a write-heavy
    /// moment into a storm of `SQLITE_BUSY`.
    pub max_readers: usize,
    /// How long a statement waits for a lock before giving up.
    pub busy_timeout: Duration,
    /// Page cache per connection, in kibibytes.
    ///
    /// SQLite's own default is ~2 MB *per connection*, which for a
    /// control plane is mostly waste. 2 MB total across a small reader
    /// set is the trade this crate makes.
    pub cache_kib: u32,
    /// `synchronous=NORMAL` (the default here) rather than `FULL`.
    ///
    /// Under WAL, `NORMAL` is durable across a process crash and can
    /// only lose the last transactions on a *power* loss. `FULL` costs
    /// an fsync per commit for a guarantee a single node without a
    /// battery-backed disk does not really have anyway.
    pub synchronous_full: bool,
}

impl Default for SqliteConfig {
    fn default() -> Self {
        Self {
            path: None,
            max_readers: 4,
            busy_timeout: Duration::from_secs(5),
            cache_kib: 2048,
            synchronous_full: false,
        }
    }
}

impl SqliteConfig {
    /// A private in-memory database. Each [`SqliteDatabase`] gets its
    /// own; nothing is shared between them.
    ///
    /// [`SqliteDatabase`]: crate::SqliteDatabase
    pub fn in_memory() -> Self {
        Self {
            // One connection can hold the whole thing: a second
            // connection to `:memory:` would open a *different*
            // database, and a reader that silently sees an empty
            // schema is the worst possible failure here.
            max_readers: 0,
            ..Self::default()
        }
    }

    pub fn at(path: impl Into<PathBuf>) -> Self {
        Self {
            path: Some(path.into()),
            ..Self::default()
        }
    }

    /// Read from the environment.
    ///
    /// * `SQLITE_PATH` — database file. Required unless
    ///   `SQLITE_IN_MEMORY` is set.
    /// * `SQLITE_IN_MEMORY` — use a throwaway in-memory database.
    /// * `WABOT_SQLITE_MAX_READERS` (default 4)
    /// * `WABOT_SQLITE_BUSY_TIMEOUT_MS` (default 5000)
    /// * `WABOT_SQLITE_CACHE_KIB` (default 2048)
    /// * `WABOT_SQLITE_SYNCHRONOUS_FULL` — trade throughput for an
    ///   fsync per commit.
    pub fn from_env() -> SqliteResult<Self> {
        let in_memory = wabot_core::env::flag("SQLITE_IN_MEMORY");
        let path = wabot_core::env::optional::<String>("SQLITE_PATH");

        let base = match (in_memory, path) {
            (true, _) => Self::in_memory(),
            (false, Some(path)) => Self::at(path),
            (false, None) => {
                return Err(SqliteError::Config(
                    "set SQLITE_PATH to the database file, or SQLITE_IN_MEMORY=1".into(),
                ))
            }
        };

        Ok(Self {
            max_readers: wabot_core::env::or("WABOT_SQLITE_MAX_READERS", base.max_readers),
            busy_timeout: Duration::from_millis(wabot_core::env::or(
                "WABOT_SQLITE_BUSY_TIMEOUT_MS",
                base.busy_timeout.as_millis() as u64,
            )),
            cache_kib: wabot_core::env::or("WABOT_SQLITE_CACHE_KIB", base.cache_kib),
            synchronous_full: wabot_core::env::flag("WABOT_SQLITE_SYNCHRONOUS_FULL"),
            ..base
        })
    }

    pub fn with_max_readers(mut self, max_readers: usize) -> Self {
        self.max_readers = max_readers;
        self
    }

    pub(crate) fn is_in_memory(&self) -> bool {
        self.path.is_none()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// An in-memory database must never hand out a second connection:
    /// `:memory:` opened twice is two *different* databases, and a
    /// reader seeing an empty schema is far worse than no reader.
    #[test]
    fn an_in_memory_database_has_no_reader_pool() {
        assert_eq!(SqliteConfig::in_memory().max_readers, 0);
        assert!(SqliteConfig::in_memory().is_in_memory());
        assert!(!SqliteConfig::at("/tmp/x.db").is_in_memory());
    }

    #[test]
    fn from_env_refuses_to_guess_a_path() {
        if std::env::var_os("SQLITE_PATH").is_some()
            || std::env::var_os("SQLITE_IN_MEMORY").is_some()
        {
            return;
        }
        assert!(matches!(
            SqliteConfig::from_env(),
            Err(SqliteError::Config(_))
        ));
    }
}