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.
from "std/dbpool" import { DbPool, dbPoolRun, dbPoolClose }Example
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
sizeclosures 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 withSQLITE_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 atdbPoolCloseor when the last handle drops. Closing lets queued jobs finish and deliver their results; a job submitted afterwards resolves to anErr. - In-memory databases. Each connection to
":memory:"is a separate database, so a pool over one must have size 1. - Record/replay.
DbPool.openfails 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 onedbOpenconnection in a program that must replay.
API reference
DbPool
pub struct DbPoolA handle to a pool of SQLite connections; see the module comment.
DbPool.clone
fn DbPool.clone(self: &DbPool): DbPoolAnother handle to the same pool, for a task of its own to hold.
DbPool.open
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
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
fn DbPool.size(self: &DbPool): i64The number of connections (and threads) in the pool.
Functions
dbPoolClose
pub fn dbPoolClose(pool: DbPool): voidShut 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
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).