OPT: Make Database an owned handle, keep the global as an optional default #28

Closed
opened 2026-10-24 23:18:15 +01:00 by NoctisWolfshadow · 0 comments
Owner

Summary

Database is currently a stateless handle over a process-wide static BACKEND: OnceLock<Backend>. Everything goes through the global, so the ORM cannot be used with more than one database per process, tests cannot get isolated in-memory databases, and set_config can only ever succeed once.

Proposal: make Database a real value that owns its backend, make the ORM generic over an Executor trait, and keep a global default on top for convenience. Both usage styles are supported:

// Global (convenience)
let user = User::find(&Database::Global, 1)?;

// Explicit (isolated, testable, multiple databases)
let user = User::find(&db, 1)?;

Motivation

  • Global mutable state is not idiomatic Rust. Most Rust database libraries take an explicit handle (&mut conn, &pool, &db).
  • Tests collide. OnceLock allows exactly one config per process, so in-memory tests share state or fight over initialization.
  • Nested-call footgun. Calling any Database method inside Database::transaction deadlocks on in-memory databases (non-reentrant Mutex) and opens a competing connection on file-backed ones. Today this is only documented, not prevented.
  • Dropping the global entirely would be inconvenient for application code that just wants User::find(1). So the global stays, but as a layer on top of the explicit API, not the foundation.

Proposed design

1. Database owns its backend

use rusqlite::{Connection, Params, Transaction};

pub struct Database {
    conn: Connection,
}

Database is Send + Sync as long as Config is, so it can be shared as &Database or Arc<Database>.

2. Executor trait: ORM code works with a Database or a Transaction

pub trait Executor {
    fn run<T>(&self, f: impl FnOnce(&Connection) -> Result<T>) -> Result<T>;
}

impl Executor for Database {
    fn run<T>(&self, f: impl FnOnce(&Connection) -> Result<T>) -> Result<T> {
        self.connection(|conn| f(conn))
    }
}

impl Executor for Transaction<'_> {
    fn run<T>(&self, f: impl FnOnce(&Connection) -> Result<T>) -> Result<T> {
        f(self) // Transaction derefs to Connection
    }
}

Model methods take &impl Executor:

impl User {
    pub fn find(db: &impl Executor, id: i64) -> Result<Option<User>> {
        db.run(|conn| {
            Ok(conn
                .query_row("SELECT id, name FROM users WHERE id = ?1", [id], |row| {
                    Ok(User { id: row.get(0)?, name: row.get(1)? })
                })
                .optional()?)
        })
    }

    pub fn insert(db: &impl Executor, name: &str) -> Result<i64> {
        db.run(|conn| {
            conn.execute("INSERT INTO users (name) VALUES (?1)", [name])?;
            Ok(conn.last_insert_rowid())
        })
    }
}

Models stay plain data (Clone, Debug, serializable). Persistence lives on the executor side, e.g. user.save(&db).

3. Global default on top

static DEFAULT: OnceLock<Database> = OnceLock::new();

impl Database {
    /// Registers `db` as the process-wide default.
    pub fn set_default(db: Database) -> Result<()> {
        DEFAULT.set(db).map_err(|_| Error::ConfigAlreadySet)
    }

    /// Returns the process-wide default.
    pub fn global() -> Result<&'static Database> {
        DEFAULT.get().ok_or(Error::ConfigNotSet)
    }

    /// Backwards-compatible shim for the current entry point.
    pub fn set_config(config: Config) -> Result<()> {
        Self::set_default(Self::new(config)?)
    }
}

Usage examples

Application startup with the global

fn main() -> Result<()> {
    Database::set_config(Config::file("app.db"))?;

    let id = User::insert(&Database::Global, "Alice")?;
    let user = User::find(&Global, id)?;
    println!("{user:?}");
    Ok(())
}

Explicit handle

let db = Database::new(Config::file("app.db"))?;

let id = User::insert(&db, "Alice")?;
let user = User::find(&db, id)?;

Multiple databases in one process

let primary = Database::new(Config::file("primary.db"))?;
let cache = Database::new(Config::memory())?;

User::insert(&primary, "Alice")?;
User::insert(&cache, "Alice (cached)")?;

Transactions (same model code, tx instead of db)

db.transaction(|tx| {
    let id = User::insert(tx, "Alice")?;
    Post::insert(tx, id, "Hello")?;
    Ok::<_, Error>(())
})?;

Isolated tests

#[test]
fn inserts_and_finds_user() -> Result<()> {
    let db = Database::new(Config::memory())?; // fresh database per test
    db.execute_batch("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);")?;

    let id = User::insert(&db, "Alice")?;
    let user = User::find(&db, id)?.unwrap();

    assert_eq!(user.name, "Alice");
    Ok(())
}

Functions that don't care which one they get

fn rename_user(db: &impl Executor, id: i64, name: &str) -> Result<()> {
    db.run(|conn| {
        conn.execute("UPDATE users SET name = ?1 WHERE id = ?2", (name, id))?;
        Ok(())
    })
}

rename_user(&db, 1, "Bob")?;       // explicit handle
rename_user(&Global, 1, "Bob")?;   // global default
rename_user(tx, 1, "Bob")?;        // inside a transaction

Caveats

  • Executor is not object-safe (generic method), so &dyn Executor is not possible. Use generics (&impl Executor).
  • Each call through &db or &Global is its own transaction (autocommit). Use transaction to group calls.
  • The global can only be set once per process. Tests that exercise set_default / Global must live in a dedicated integration test file (separate binary), because OnceLock cannot be reset.

Tasks

  • Add Database::new(Config) and move conn into the struct
  • Change connection, transaction, execute, execute_batch to take &self
  • Add Executor trait with impls for Database and Transaction
  • Add Database::set_default, Database::global, and keep set_config as a shim
  • Add Global executor and its execute / execute_batch / transaction helpers
  • Port ORM methods to &impl Executor
  • Update docs: replace the "don't call Database methods inside the closure" rule with the Global caveat above
  • Convert existing tests to per-test Database::new(Config::memory())
  • Add one integration test (own file) covering set_default / Global / ConfigAlreadySet
  • Add a changelog entry for the breaking rename

Open questions

  1. Should Global get sugar on models too (e.g. User::find_global(1)), or is User::find(&Global, 1) enough?
  2. Should Database::global() have a panicking variant for application code, or stay Result-only?
  3. Is Config: Send + Sync guaranteed? Database needs it to be usable from a static and across threads.
## Summary `Database` is currently a stateless handle over a process-wide `static BACKEND: OnceLock<Backend>`. Everything goes through the global, so the ORM cannot be used with more than one database per process, tests cannot get isolated in-memory databases, and `set_config` can only ever succeed once. Proposal: make `Database` a real value that owns its backend, make the ORM generic over an `Executor` trait, and keep a global default on top for convenience. Both usage styles are supported: ```rust // Global (convenience) let user = User::find(&Database::Global, 1)?; // Explicit (isolated, testable, multiple databases) let user = User::find(&db, 1)?; ``` ## Motivation - **Global mutable state is not idiomatic Rust.** Most Rust database libraries take an explicit handle (`&mut conn`, `&pool`, `&db`). - **Tests collide.** `OnceLock` allows exactly one config per process, so in-memory tests share state or fight over initialization. - **Nested-call footgun.** Calling any `Database` method inside `Database::transaction` deadlocks on in-memory databases (non-reentrant `Mutex`) and opens a competing connection on file-backed ones. Today this is only documented, not prevented. - **Dropping the global entirely would be inconvenient** for application code that just wants `User::find(1)`. So the global stays, but as a layer on top of the explicit API, not the foundation. ## Proposed design ### 1. `Database` owns its backend ```rust use rusqlite::{Connection, Params, Transaction}; pub struct Database { conn: Connection, } ``` `Database` is `Send + Sync` as long as `Config` is, so it can be shared as `&Database` or `Arc<Database>`. ### 2. `Executor` trait: ORM code works with a `Database` or a `Transaction` ```rust pub trait Executor { fn run<T>(&self, f: impl FnOnce(&Connection) -> Result<T>) -> Result<T>; } impl Executor for Database { fn run<T>(&self, f: impl FnOnce(&Connection) -> Result<T>) -> Result<T> { self.connection(|conn| f(conn)) } } impl Executor for Transaction<'_> { fn run<T>(&self, f: impl FnOnce(&Connection) -> Result<T>) -> Result<T> { f(self) // Transaction derefs to Connection } } ``` Model methods take `&impl Executor`: ```rust impl User { pub fn find(db: &impl Executor, id: i64) -> Result<Option<User>> { db.run(|conn| { Ok(conn .query_row("SELECT id, name FROM users WHERE id = ?1", [id], |row| { Ok(User { id: row.get(0)?, name: row.get(1)? }) }) .optional()?) }) } pub fn insert(db: &impl Executor, name: &str) -> Result<i64> { db.run(|conn| { conn.execute("INSERT INTO users (name) VALUES (?1)", [name])?; Ok(conn.last_insert_rowid()) }) } } ``` Models stay plain data (`Clone`, `Debug`, serializable). Persistence lives on the executor side, e.g. `user.save(&db)`. ### 3. Global default on top ```rust static DEFAULT: OnceLock<Database> = OnceLock::new(); impl Database { /// Registers `db` as the process-wide default. pub fn set_default(db: Database) -> Result<()> { DEFAULT.set(db).map_err(|_| Error::ConfigAlreadySet) } /// Returns the process-wide default. pub fn global() -> Result<&'static Database> { DEFAULT.get().ok_or(Error::ConfigNotSet) } /// Backwards-compatible shim for the current entry point. pub fn set_config(config: Config) -> Result<()> { Self::set_default(Self::new(config)?) } } ``` ## Usage examples ### Application startup with the global ```rust fn main() -> Result<()> { Database::set_config(Config::file("app.db"))?; let id = User::insert(&Database::Global, "Alice")?; let user = User::find(&Global, id)?; println!("{user:?}"); Ok(()) } ``` ### Explicit handle ```rust let db = Database::new(Config::file("app.db"))?; let id = User::insert(&db, "Alice")?; let user = User::find(&db, id)?; ``` ### Multiple databases in one process ```rust let primary = Database::new(Config::file("primary.db"))?; let cache = Database::new(Config::memory())?; User::insert(&primary, "Alice")?; User::insert(&cache, "Alice (cached)")?; ``` ### Transactions (same model code, `tx` instead of `db`) ```rust db.transaction(|tx| { let id = User::insert(tx, "Alice")?; Post::insert(tx, id, "Hello")?; Ok::<_, Error>(()) })?; ``` ### Isolated tests ```rust #[test] fn inserts_and_finds_user() -> Result<()> { let db = Database::new(Config::memory())?; // fresh database per test db.execute_batch("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);")?; let id = User::insert(&db, "Alice")?; let user = User::find(&db, id)?.unwrap(); assert_eq!(user.name, "Alice"); Ok(()) } ``` ### Functions that don't care which one they get ```rust fn rename_user(db: &impl Executor, id: i64, name: &str) -> Result<()> { db.run(|conn| { conn.execute("UPDATE users SET name = ?1 WHERE id = ?2", (name, id))?; Ok(()) }) } rename_user(&db, 1, "Bob")?; // explicit handle rename_user(&Global, 1, "Bob")?; // global default rename_user(tx, 1, "Bob")?; // inside a transaction ``` ## Caveats - **`Executor` is not object-safe** (generic method), so `&dyn Executor` is not possible. Use generics (`&impl Executor`). - **Each call through `&db` or `&Global` is its own transaction (autocommit).** Use `transaction` to group calls. - **The global can only be set once per process.** Tests that exercise `set_default` / `Global` must live in a dedicated integration test file (separate binary), because `OnceLock` cannot be reset. ## Tasks - [ ] Add `Database::new(Config)` and move `conn` into the struct - [ ] Change `connection`, `transaction`, `execute`, `execute_batch` to take `&self` - [ ] Add `Executor` trait with impls for `Database` and `Transaction` - [ ] Add `Database::set_default`, `Database::global`, and keep `set_config` as a shim - [ ] Add `Global` executor and its `execute` / `execute_batch` / `transaction` helpers - [ ] Port ORM methods to `&impl Executor` - [ ] Update docs: replace the "don't call `Database` methods inside the closure" rule with the `Global` caveat above - [ ] Convert existing tests to per-test `Database::new(Config::memory())` - [ ] Add one integration test (own file) covering `set_default` / `Global` / `ConfigAlreadySet` - [ ] Add a changelog entry for the breaking rename ## Open questions 1. Should `Global` get sugar on models too (e.g. `User::find_global(1)`), or is `User::find(&Global, 1)` enough? 2. Should `Database::global()` have a panicking variant for application code, or stay `Result`-only? 3. Is `Config: Send + Sync` guaranteed? `Database` needs it to be usable from a `static` and across threads.
Sign in to join this conversation.
No description provided.