Struct AsyncDb

Source

pub struct AsyncDb { /* private fields */ }

Available on crate feature async only.

Expand description

Async-facing wrapper around the blocking Db.

AsyncDb is cheap to clone (one Arc bump) so it can be shared across spawned tasks without locking. The blocking engine sits behind a single Arc<Db>; every async method hands its body off to the blocking thread pool.

Public construction goes through AsyncDb::open / AsyncDb::open_with / AsyncDb::memory / AsyncDb::memory_with / AsyncDb::open_readonly / AsyncDb::from_blocking.

Implementations§

Source §

impl AsyncDb

Source

pub fn from_blocking(db: Db) -> Self

Construct an AsyncDb from an already-opened blocking Db.

Synchronous on purpose — wrapping an in-hand Db does no I/O. Useful when the caller already opened the database from a blocking context (e.g. CLI bootstrap) and wants to drive it async-style from the rest of the program.

Source

pub async fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Open or create a file-backed database at path with default configuration. See Db::open.

§Errors

As Db::open.

Source

pub async fn open_with<P: AsRef<Path>>(path: P, config: Config) -> Result<Self>

Open or create a file-backed database with config. See Db::open_with.

§Errors

As Db::open_with.

Source

pub async fn memory() -> Result<Self>

Open a fresh in-memory database. See Db::memory.

§Errors

As Db::memory.

Source

pub async fn memory_with(config: Config) -> Result<Self>

As AsyncDb::memory with a caller-supplied Config.

§Errors

As Db::memory_with.

Source

pub async fn open_readonly<P: AsRef<Path>>(path: P) -> Result<Self>

Open the database at path read-only. See Db::open_readonly.

§Errors

As Db::open_readonly.

Source

pub fn as_blocking(&self) -> &Db

Borrow the underlying blocking Db.

Useful when async code needs to hand a &Db to a third-party API that only takes the blocking type — note the borrow is scoped to the local task, not the blocking pool.

Source

pub async fn insert<T>(&self, doc: T) -> Result<Id>
where T: Document + Send + 'static,

Insert doc. See Db::insert.

§Errors

As Db::insert.

Source

pub async fn get<T>(&self, id: Id) -> Result<Option<T>>
where T: Document + Send + 'static,

Fetch the document at id. See Db::get.

§Errors

As Db::get.

Source

pub async fn update<T, F>(&self, id: Id, f: F) -> Result<()>
where T: Document + Send + 'static, F: FnOnce(&mut T) + Send + 'static,

Update the document at id. See Db::update.

The closure runs synchronously inside the blocking task, so it must be Send + 'static. This mirrors the wider “closure runs on the blocking pool” contract documented on AsyncDb::transaction.

§Errors

As Db::update.

Source

pub async fn delete<T>(&self, id: Id) -> Result<bool>
where T: Document + Send + 'static,

Delete the document at id. See Db::delete.

§Errors

As Db::delete.

Source

pub async fn upsert<T>(&self, id: Id, doc: T) -> Result<()>
where T: Document + Send + 'static,

Insert-or-replace the document at id. See Db::upsert.

§Errors

As Db::upsert.

Source

pub async fn find_unique<T, K>( &self, index_name: &str, key: K, ) -> Result<Option<T>>
where T: Document + Send + 'static, K: Into<Dynamic> + Send + 'static,

Point lookup on a Unique index. See Db::find_unique.

§Errors

As Db::find_unique.

Source

pub async fn all<T>(&self) -> Result<Vec<T>>
where T: Document + Send + 'static,

Materialise the collection’s primary B-tree into Vec<T>. See Db::all.

Streaming async iteration is intentionally not wrapped in this phase — the entire collection is collected inside the blocking task. For very large collections, drive the blocking Db::iter_all from a dedicated tokio::task::spawn_blocking (or equivalent) until the async streaming surface lands.

§Errors

As Db::all.

Source

pub async fn transaction<R, F>(&self, body: F) -> Result<R>
where R: Send + 'static, F: FnOnce(&mut WriteTxn<'_>) -> Result<R> + Send + 'static,

Run a closure inside a write transaction. See Db::transaction.

§Closure contract

The closure runs synchronously inside the blocking task, so it must be Send + 'static; the return value R likewise. No async fn inside the closure — that is a deliberate “async-over-blocking” restriction, matching the contract used by sqlx and other async-over-sync database wrappers.

§Errors

As Db::transaction.

Source

pub async fn read_transaction<R, F>(&self, body: F) -> Result<R>
where R: Send + 'static, F: FnOnce(&ReadTxn<'_>) -> Result<R> + Send + 'static,

Run a closure inside a read transaction. See Db::read_transaction.

Same Send + 'static closure restriction as AsyncDb::transaction.

§Errors

As Db::read_transaction.

Source

pub async fn backup_to<P: AsRef<Path>>(&self, dest: P) -> Result<()>

Hot-backup the database to dest. See Db::backup_to.

§Errors

As Db::backup_to.

Source

pub async fn attach( &mut self, path: P, namespace: impl Into<String>, ) -> Result<()>
where P: AsRef<Path>,

Attach a read-only .obj file under namespace. See Db::attach.

Takes &mut self because the blocking Db::attach takes &mut Db. We temporarily unwrap the Arc<Db> (it must be uniquely owned at this point) so the blocking task can take the &mut. If the Arc is shared, attach falls back to Error::Busy with the WriterInProcess kind — clone the AsyncDb only after all attach / detach calls.