async_sqlite/
lib.rs

1//! # async-sqlite
2//!
3//! A library to interact with sqlite from an async context.
4//!
5//! This library is tested on both [tokio](https://docs.rs/tokio/latest/tokio/)
6//! and [smol](https://docs.rs/smol/latest/smol/), however
7//! it should be compatible with all async runtimes.
8//!
9//! ## Usage
10//!
11//! A `Client` represents a single background sqlite3 connection that can be called
12//! concurrently from any thread in your program.
13//!
14//! To create a sqlite client and run a query:
15//!
16//! ```rust
17//! use async_sqlite::{ClientBuilder, JournalMode};
18//!
19//! # async fn run() -> Result<(), async_sqlite::Error> {
20//! let client = ClientBuilder::new()
21//!                 .path("/path/to/db.sqlite3")
22//!                 .journal_mode(JournalMode::Wal)
23//!                 .open()
24//!                 .await?;
25//!
26//! let value: String = client.conn(|conn| {
27//!     conn.query_row("SELECT val FROM testing WHERE id=?", [1], |row| row.get(0))
28//! }).await?;
29//!
30//! println!("Value is: {value}");
31//! # Ok(())
32//! }
33//! ```
34//!
35//! Async operations that are queued and then canceled before the worker starts
36//! them are skipped. [`ClientBuilder::queue_capacity()`] and
37//! [`PoolBuilder::queue_capacity()`] can be used to bound worker queues;
38//! operations return [`Error::QueueFull`] when the selected queue is full.
39//!
40//! A `Pool` represents a collection of background sqlite3 connections that can be
41//! called concurrently from any thread in your program.
42//!
43//! `PoolBuilder::new().open()` and `path(":memory:")` use a single anonymous
44//! in-memory connection by default, since separate SQLite `:memory:`
45//! connections do not share schema or data. File-backed pools default to the
46//! logical CPU count. For multiple connections to a named in-memory database,
47//! use `shared_memory("name")`; this uses SQLite shared-cache mode, which has
48//! caveats, so prefer a file-backed database when possible.
49//!
50//! To create a sqlite pool and run a query:
51//!
52//! ```rust
53//! use async_sqlite::{JournalMode, PoolBuilder};
54//!
55//! # async fn run() -> Result<(), async_sqlite::Error> {
56//! let pool = PoolBuilder::new()
57//!               .path("/path/to/db.sqlite3")
58//!               .journal_mode(JournalMode::Wal)
59//!               .open()
60//!               .await?;
61//!
62//! let value: String = pool.conn(|conn| {
63//!     conn.query_row("SELECT val FROM testing WHERE id=?", [1], |row| row.get(0))
64//! }).await?;
65//!
66//! println!("Value is: {value}");
67//! # Ok(())
68//! # }
69//! ```
70//!
71//! ## Cargo Features
72//!
73//! This library tries to export almost all features that the underlying
74//! [rusqlite](https://docs.rs/rusqlite/latest/rusqlite/) library contains.
75//!
76//! A notable difference is that the `bundled` feature is **enabled** by default
77//! alongside rusqlite's `cache` and `ffi-sqlite-wasm-rs` defaults. These defaults
78//! can be disabled with the following line in your Cargo.toml:
79//!
80//! ```toml
81//! async-sqlite = { version = "*", default-features = false }
82//! ```
83
84pub use rusqlite;
85
86mod client;
87mod error;
88mod pool;
89
90pub use client::{Client, ClientBuilder, JournalMode};
91pub use error::Error;
92pub use pool::{Pool, PoolBuilder};
async_sqlite/lib.rs

async_sqlite/
lib.rs
