Struct AzothDb 

pub struct AzothDb { /* private fields */ }

Unified Axiom database

Bundles together canonical store, projection store, and projector for easy management.

Implementations

impl AzothDb

pub fn backup_with_options<P: AsRef<Path>>( &self, dir: P, options: &BackupOptions, ) -> Result<()>

Backup with custom options (encryption and compression)

pub fn restore_with_options<P: AsRef<Path>, Q: AsRef<Path>>( backup_dir: P, target_path: Q, options: &BackupOptions, ) -> Result<Self>

Restore from backup with custom options

impl AzothDb

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

Open an Axiom database at the given path

Creates subdirectories:

• {path}/canonical/ - LMDB canonical store
• {path}/projection.db - SQLite projection store

pub fn open_with_config( base_path: PathBuf, canonical_config: CanonicalConfig, projection_config: ProjectionConfig, ) -> Result<Self>

Open with custom configurations

pub fn open_with_projector_config( base_path: PathBuf, canonical_config: CanonicalConfig, projection_config: ProjectionConfig, projector_config: ProjectorConfig, ) -> Result<Self>

Open with custom projector config

pub fn canonical(&self) -> &Arc<LmdbCanonicalStore>

Get reference to canonical store

pub fn projection(&self) -> &Arc<SqliteProjectionStore>

Get reference to projection store

pub fn projection_write_conn(&self) -> &Arc<Mutex<Connection>>

Get the projection write connection.

Use this for migrations, DDL, and projector event application. For read-only queries, prefer query() / query_async() which automatically use the read pool for concurrent access.

Example

let conn = db.projection_write_conn();
let guard = conn.lock();
guard.execute("INSERT INTO ...", params![])?;

pub fn projection_connection(&self) -> &Arc<Mutex<Connection>>

👎Deprecated since 0.3.0: Use query()/query_async() for reads, projection_write_conn() for writes

Get the underlying SQLite connection for the projection store.

Deprecated: prefer projection_write_conn() for writes and query() / query_async() for reads. This method returns the write connection, which contends with the projector.

pub fn projector(&self) -> &Projector<LmdbCanonicalStore, SqliteProjectionStore>

Get reference to projector

pub fn event_notify(&self) -> Arc<Notify>

Get the shared event notification handle.

This Notify fires after every successful event append. Consumers (event processors, custom projectors) can call notify.notified().await to wake immediately when new events are available, eliminating polling.

pub fn base_path(&self) -> &Path

Get the base path

pub fn migrate(&self, manager: &MigrationManager) -> Result<()>

Run migrations on the projection store

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

Backup the entire database to a directory

Follows the safe backup workflow:

1. Pause ingestion
2. Seal canonical
3. Run projector to catch up
4. Backup both stores
5. Resume ingestion

pub fn restore_from<P: AsRef<Path>>( backup_dir: P, target_path: P, ) -> Result<Self>

Restore from a backup directory

pub async fn query_async<F, R>(&self, f: F) -> Result<R>

where F: FnOnce(&Connection) -> Result<R> + Send + 'static, R: Send + 'static,

Execute an async SQL query on the projection store

This is a convenience wrapper around projection().query_async().

Example

let balance: i64 = db.query_async(|conn| {
    conn.query_row("SELECT balance FROM accounts WHERE id = ?1", [1], |row| row.get(0))
}).await?;

pub fn query<F, R>(&self, f: F) -> Result<R>

where F: FnOnce(&Connection) -> Result<R>,

Execute a synchronous SQL query on the projection store

Example

let balance: i64 = db.query(|conn| {
    conn.query_row("SELECT balance FROM accounts WHERE id = ?1", [1], |row| row.get(0))
})?;

pub async fn execute_async<F>(&self, f: F) -> Result<()>

where F: FnOnce(&Connection) -> Result<()> + Send + 'static,

Execute arbitrary SQL statements asynchronously

Example

db.execute_async(|conn| {
    conn.execute("CREATE TABLE balances (id INTEGER PRIMARY KEY, amount INTEGER)", [])?;
    Ok(())
}).await?;

pub fn execute<F>(&self, f: F) -> Result<()>

where F: FnOnce(&Connection) -> Result<()>,

Execute arbitrary SQL statements synchronously

Example

db.execute(|conn| {
    conn.execute("CREATE TABLE balances (id INTEGER PRIMARY KEY, amount INTEGER)", [])?;
    Ok(())
})?;

pub fn transaction<F>(&self, f: F) -> Result<()>

where F: FnOnce(&Transaction<'_>) -> Result<()>,

Execute a SQL transaction

Example

db.transaction(|tx| {
    tx.execute("INSERT INTO accounts (id, balance) VALUES (?1, ?2)", params![1, 100])?;
    tx.execute("INSERT INTO accounts (id, balance) VALUES (?1, ?2)", params![2, 200])?;
    Ok(())
})?;

pub async fn transaction_async<F>(&self, f: F) -> Result<()>

where F: FnOnce(&Transaction<'_>) -> Result<()> + Send + 'static,

Execute a SQL transaction asynchronously

pub async fn submit_write<F, R>(&self, f: F) -> Result<R>

where F: for<'a> FnOnce(&mut LmdbWriteTxn<'a>) -> Result<R> + Send + 'static, R: Send + 'static,

Execute a write operation on the canonical store asynchronously.

Opens a write transaction, passes it to the closure, and commits atomically – all inside spawn_blocking. This replaces ad-hoc spawn_blocking wrappers at each call site.

Example

use azoth_core::traits::CanonicalTxn;

db.submit_write(|txn| {
    txn.put_state(b"balance", b"100")?;
    txn.append_event(b"{\"type\":\"deposit\",\"amount\":100}")?;
    Ok(())
}).await?;

pub fn write_batch(&self) -> WriteBatch<'_>

Create a new write batch for atomic multi-operation commits.

Example

let mut batch = db.write_batch();
batch.put(b"key1", b"value1");
batch.put(b"key2", b"value2");
batch.append_event(b"batch_update:{\"keys\":2}");
let info = batch.commit()?;

pub fn scan_prefix(&self, prefix: &[u8]) -> Result<Box<dyn StateIter>>

Scan state keys with a prefix

Returns an iterator over (key, value) pairs with keys starting with the prefix.

Example

use azoth_core::traits::StateIter;

let mut iter = db.scan_prefix(b"user:")?;
while let Some((key, value)) = iter.next()? {
    println!("Key: {:?}, Value: {:?}", key, value);
}

pub fn range( &self, start: &[u8], end: Option<&[u8]>, ) -> Result<Box<dyn StateIter>>

Iterate state keys in a range

Example

use azoth_core::traits::StateIter;

let mut iter = db.range(b"user:a", Some(b"user:z"))?;
while let Some((key, value)) = iter.next()? {
    println!("Key: {:?}, Value: {:?}", key, value);
}

pub fn prepare_shutdown(&self) -> Result<()>

Prepare database for shutdown

This method should be called before closing the database to ensure all pending operations complete. It:

1. Pauses ingestion
2. Seals the canonical store
3. Runs projector to catch up

After calling this, you can create a final checkpoint using CheckpointManager::shutdown_checkpoint(), then call close().

Example

// Prepare for shutdown
db.prepare_shutdown()?;

// Create final checkpoint (async)
checkpoint_manager.shutdown_checkpoint().await?;

// Close database
db.close()?;

pub fn close(self) -> Result<()>

Close the database (ensures clean shutdown)

For graceful shutdown with checkpoint, call shutdown() first.