Embedded Rust

Use the workspace crate

The crate is source-delivered and not currently published to a package registry. It starts no network server and has no ForgeZero dependency.

[dependencies]
qirava = { path = "/path/to/qirava/db/crates/qirava" }

Open and transact

Load the original secret from your host keystore. Reopen requires that exact key. RootKey redacts Debug and zeroizes its held buffer on drop; the host must protect and clear any source copy. For a host keystore or external authority, implement KeyProvider and use Database::open_with_provider. Provider errors never generate a replacement key.

use qirava::{Database, Operation, RootKey, TransactionRequest};

fn create(secret: [u8; 32]) -> Result<(), Box<dyn std::error::Error>> {
    let db = Database::open("./customer-data", RootKey::from_bytes(secret))?;
    db.execute(TransactionRequest {
        request_id: "create-customers-v1".into(),
        operations: vec![Operation::CreateCollection {
            name: "customers".into(),
            schema: None,
            unique: vec![vec!["email".into()]],
        }],
    })?;
    Ok(())
}

Own the process and lifecycle

Database is Send + Sync and Clone; cloned handles share the engine and exclusive directory lock. Synchronous calls may block on coordination, crypto and I/O. Use your async runtime’s blocking pool or the bounded ScheduledDatabase interface.

The embedded process is trusted. execute_authorized lets your host enforce transaction resources, including receipt replay. The host must also authorize exposed metadata, uploads and objects. Do not expose the owning handle to untrusted code.