use std::{path::Path, time::Duration, time::Instant};
use rusqlite::Connection;
pub const JOURNAL_MODE: &str = "wal";
pub const SYNCHRONOUS: i64 = 1;
pub const BUSY_TIMEOUT_MS: u64 = 15_000;
pub fn open_configured(path: impl AsRef<Path>) -> rusqlite::Result<Connection> {
let connection = Connection::open(path)?;
configure(&connection)?;
Ok(connection)
}
pub fn configure(connection: &Connection) -> rusqlite::Result<()> {
connection.busy_timeout(Duration::from_millis(BUSY_TIMEOUT_MS))?;
connection.execute_batch(
"PRAGMA synchronous = NORMAL;
PRAGMA foreign_keys = ON;",
)?;
ensure_wal(connection)
}
const WAL_CONVERSION_BUDGET: Duration = Duration::from_millis(BUSY_TIMEOUT_MS);
const WAL_FIRST_BACKOFF_MS: u64 = 1;
const WAL_BACKOFF_CAP_MS: u64 = 25;
const WAL_CONVERSION_ATTEMPTS: u64 = 1_024;
const WAL_BACKOFF_RAMP: u64 = {
let mut pause = WAL_FIRST_BACKOFF_MS;
let mut below_cap = 0;
while pause < WAL_BACKOFF_CAP_MS {
pause *= 2;
below_cap += 1;
}
below_cap
};
const _: () = assert!(
(WAL_CONVERSION_ATTEMPTS - 1 - WAL_BACKOFF_RAMP) * WAL_BACKOFF_CAP_MS > BUSY_TIMEOUT_MS
);
fn ensure_wal(connection: &Connection) -> rusqlite::Result<()> {
ensure_wal_within(connection, &mut WallClock::start())
}
trait RetryClock {
fn elapsed(&self) -> Duration;
fn pause(&mut self, pause: Duration);
}
struct WallClock {
start: Instant,
}
impl WallClock {
fn start() -> Self {
Self {
start: Instant::now(),
}
}
}
impl RetryClock for WallClock {
fn elapsed(&self) -> Duration {
self.start.elapsed()
}
fn pause(&mut self, pause: Duration) {
std::thread::sleep(pause);
}
}
fn ensure_wal_within(connection: &Connection, clock: &mut impl RetryClock) -> rusqlite::Result<()> {
let cap = Duration::from_millis(WAL_BACKOFF_CAP_MS);
let mut backoff = Duration::from_millis(WAL_FIRST_BACKOFF_MS);
for _ in 1..WAL_CONVERSION_ATTEMPTS {
match attempt_wal(connection) {
Err(err) if is_busy(&err) && clock.elapsed() < WAL_CONVERSION_BUDGET => {
clock.pause(backoff);
backoff = backoff.saturating_mul(2).min(cap);
}
settled => return settled,
}
}
attempt_wal(connection)
}
fn attempt_wal(connection: &Connection) -> rusqlite::Result<()> {
let current: String = connection.query_row("PRAGMA journal_mode", [], |row| row.get(0))?;
if current.eq_ignore_ascii_case(JOURNAL_MODE) {
return Ok(());
}
connection.query_row("PRAGMA journal_mode = WAL", [], |row| {
row.get::<_, String>(0)
})?;
Ok(())
}
pub(crate) fn is_busy(error: &rusqlite::Error) -> bool {
matches!(
error,
rusqlite::Error::SqliteFailure(failure, _)
if failure.code == rusqlite::ErrorCode::DatabaseBusy
|| failure.code == rusqlite::ErrorCode::DatabaseLocked
)
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConnectionSettings {
journal_mode: String,
synchronous: i64,
busy_timeout_ms: i64,
}
impl ConnectionSettings {
pub fn read_back(connection: &Connection) -> rusqlite::Result<Self> {
let journal_mode: String =
connection.query_row("PRAGMA journal_mode", [], |row| row.get(0))?;
let synchronous: i64 = connection.query_row("PRAGMA synchronous", [], |row| row.get(0))?;
let busy_timeout_ms: i64 =
connection.query_row("PRAGMA busy_timeout", [], |row| row.get(0))?;
Ok(Self {
journal_mode: journal_mode.to_lowercase(),
synchronous,
busy_timeout_ms,
})
}
#[must_use]
pub fn journal_mode(&self) -> &str {
&self.journal_mode
}
#[must_use]
pub const fn synchronous(&self) -> i64 {
self.synchronous
}
#[must_use]
pub const fn busy_timeout_ms(&self) -> i64 {
self.busy_timeout_ms
}
}
#[cfg(test)]
mod tests {
use std::io::ErrorKind;
use std::path::PathBuf;
use super::*;
struct FreshFile(PathBuf);
impl FreshFile {
fn new(test: &str) -> Self {
let mut path = std::env::temp_dir();
path.push(format!(
"happenstance-sqlite-wal-{}-{test}.db",
std::process::id()
));
let file = Self(path);
file.remove();
file
}
fn remove(&self) {
for suffix in ["", "-wal", "-shm", "-journal"] {
let mut path = self.0.as_os_str().to_os_string();
path.push(suffix);
match std::fs::remove_file(PathBuf::from(path)) {
Err(err) if err.kind() != ErrorKind::NotFound => {
eprintln!("could not remove a scratch file: {err}");
}
_ => {}
}
}
}
}
impl Drop for FreshFile {
fn drop(&mut self) {
self.remove();
}
}
struct Scripted {
now: Duration,
pauses: Vec<Duration>,
release_at: Option<Duration>,
holder: Option<Connection>,
}
impl Scripted {
fn holding(holder: Connection, release_at: Option<Duration>) -> Self {
Self {
now: Duration::ZERO,
pauses: Vec::new(),
release_at,
holder: Some(holder),
}
}
}
impl RetryClock for Scripted {
fn elapsed(&self) -> Duration {
self.now
}
fn pause(&mut self, pause: Duration) {
self.pauses.push(pause);
self.now += pause;
if self.release_at.is_some_and(|at| self.now >= at)
&& let Some(holder) = self.holder.take()
{
holder
.execute_batch("ROLLBACK")
.expect("the holder's transaction is still open");
}
}
}
fn reserved(file: &FreshFile) -> Connection {
let holder = Connection::open(&file.0).expect("a temp file opens");
holder
.execute_batch("BEGIN IMMEDIATE")
.expect("nothing else holds the fresh file");
holder
}
fn opener(file: &FreshFile) -> Connection {
let connection = Connection::open(&file.0).expect("a temp file opens");
connection
.busy_timeout(Duration::from_millis(BUSY_TIMEOUT_MS))
.expect("the busy timeout installs");
connection
}
#[test]
fn a_conversion_held_past_the_old_attempt_bound_is_outlasted() {
let file = FreshFile::new("outlasted");
let mut clock = Scripted::holding(reserved(&file), Some(Duration::from_millis(250)));
let connection = opener(&file);
let outcome = ensure_wal_within(&connection, &mut clock);
assert!(
outcome.is_ok(),
"refused after {} pauses totalling {:?}: {outcome:?}",
clock.pauses.len(),
clock.now
);
assert!(clock.holder.is_none(), "the lock was held until released");
let mode = ConnectionSettings::read_back(&connection).expect("pragmas read");
assert_eq!(mode.journal_mode(), JOURNAL_MODE);
}
#[test]
fn a_lock_never_released_ends_at_the_budget_as_busy() {
let file = FreshFile::new("never-released");
let mut clock = Scripted::holding(reserved(&file), None);
let connection = opener(&file);
let outcome = ensure_wal_within(&connection, &mut clock);
let err = outcome.expect_err("a lock never released must be reported");
assert!(is_busy(&err), "the driver's own busy error: {err:?}");
assert!(
clock.now >= WAL_CONVERSION_BUDGET,
"gave up at {:?}, inside the budget",
clock.now
);
assert!(
clock.now < WAL_CONVERSION_BUDGET + Duration::from_millis(WAL_BACKOFF_CAP_MS),
"overshot the budget by more than one pause: {:?}",
clock.now
);
assert!(
u64::try_from(clock.pauses.len()).expect("a pause count fits u64")
< WAL_CONVERSION_ATTEMPTS - 1,
"the clock, not the ceiling, ended it"
);
}
#[test]
fn the_backoff_doubles_from_one_millisecond_and_holds_at_the_cap() {
let file = FreshFile::new("backoff-shape");
let mut clock = Scripted::holding(reserved(&file), None);
let connection = opener(&file);
ensure_wal_within(&connection, &mut clock).expect_err("the lock is never released");
let millis: Vec<u128> = clock.pauses.iter().map(Duration::as_millis).collect();
assert_eq!(millis.get(..7), Some(&[1, 2, 4, 8, 16, 25, 25][..]));
assert!(
millis.iter().all(|&pause| pause <= 25),
"no pause exceeds the cap: {millis:?}"
);
}
struct Frozen {
pauses: u64,
}
impl RetryClock for Frozen {
fn elapsed(&self) -> Duration {
Duration::ZERO
}
fn pause(&mut self, _pause: Duration) {
self.pauses += 1;
}
}
#[test]
fn a_clock_that_never_advances_still_ends_at_the_ceiling() {
let file = FreshFile::new("frozen-clock");
let holder = reserved(&file);
let connection = opener(&file);
let mut clock = Frozen { pauses: 0 };
let outcome = ensure_wal_within(&connection, &mut clock);
let err = outcome.expect_err("a lock never released must be reported");
assert!(is_busy(&err), "the driver's own busy error: {err:?}");
assert_eq!(clock.pauses, WAL_CONVERSION_ATTEMPTS - 1);
drop(holder);
}
}