Skip to content

std/dbpool ​

A fixed pool of SQLite connections, each owned by a dedicated OS thread. A query run on the green-task scheduler's thread stops every other task until it finishes; through a DbPool it runs on a pool thread while the awaiting task parks, so cheap requests keep being served behind a slow one.

milo
from "std/dbpool" import { DbPool, dbPoolRun, dbPoolClose }

Example ​

milo
from "std/sqlite" import { Database, dbScalar }
from "std/dbpool" import { DbPool, dbPoolRun, dbPoolClose }

fn main(): i32 {
    // size 0: one connection per core; the setup statements run on every connection
    let pool = DbPool.openWith("/tmp/app.db", 0, ["PRAGMA journal_size_limit=67108864"])!
    let n = dbPoolRun(pool, move(db: &Database): i64 => {
        return dbScalar(db, "SELECT 40 + 2", [])! ?? 0
    }).await()!
    print(n)
    dbPoolClose(pool)
    return 0
}

The closure gets a &Database and uses the ordinary std/sqlite calls, so checked SQL and @derive(Row) fetches are checked at compile time exactly as they are outside a pool. The closure runs on another OS thread, so the checker holds its captures to Send and rejects mutable globals it reaches, as for Promise.blocking.

Behavior ​

  • Bounded. At most size closures run at once; the rest wait FIFO. The pool never grows, so a closure must not wait on another job of the same pool (with every thread so blocked, nothing runs the job it waits for).
  • Writes. SQLite admits one writer at a time and the pool does not route reads and writes. Concurrent writers wait on the database lock for up to busy_timeout (5 s), then fail with SQLITE_BUSY. Keep write transactions short (dbBeginImmediate), and for a write-heavy app send writes through a second pool of size 1.
  • Sharing. clone() gives each task its own handle; the pool shuts down at dbPoolClose or when the last handle drops. Closing lets queued jobs finish and deliver their results; a job submitted afterwards resolves to an Err.
  • In-memory databases. Each connection to ":memory:" is a separate database, so a pool over one must have size 1.
  • Record/replay. DbPool.open fails while recording or replaying: which pool thread runs which job is not recorded, so a replay could not answer each query from its own records. Use one dbOpen connection in a program that must replay.

API reference ​

DbPool ​

milo
pub struct DbPool

A handle to a pool of SQLite connections; see the module comment.

DbPool.clone ​

milo
fn DbPool.clone(self: &DbPool): DbPool

Another handle to the same pool, for a task of its own to hold.

DbPool.open ​

milo
fn DbPool.open(path: string, size: i64): Result<DbPool>

Open size connections to path, each on a thread of its own; size <= 0 means one per core. Errs, with nothing left running, if any connection fails to open.

DbPool.openWith ​

milo
fn DbPool.openWith(path: string, size: i64, setup: Vec<string>): Result<DbPool>

Like open, then run each statement in setup on every connection before the pool takes work (PRAGMA journal_size_limit=..., PRAGMA cache_size=...). Plain SQL rather than a callback: it runs on the opening thread before any worker exists, so a failure fails openWith with the statement named, and no job can observe a connection that is half set up.

DbPool.size ​

milo
fn DbPool.size(self: &DbPool): i64

The number of connections (and threads) in the pool.

Functions ​

dbPoolClose ​

milo
pub fn dbPoolClose(pool: DbPool): void

Shut the pool down now for every handle: no new jobs are taken (a later dbPoolRun resolves to an Err), the queued ones finish and deliver their results, and the connections close. Blocks the calling thread until the workers have exited; a second close, from another handle, returns at once. Dropping the last handle does the same.

dbPoolRun ​

milo
pub fn dbPoolRun<T>(pool: &DbPool, f: move (&Database) => T): Promise<T>

Run f on one of the pool's connections, on that connection's thread. Awaiting the Promise from a green task parks only that task. At most pool.size() closures run at once; the rest queue FIFO. Resolves to an Err if the pool was closed first. @thread: f runs on a pool worker, so its captures must be Send and the checker rejects unsynchronized mutable globals reached from its body.

Standalone rather than a method: a generic method taking a closure over the struct's own type monomorphizes recursively (see promiseAll).