Struct Database 

pub struct Database { /* private fields */ }

An open Citadel database (Send + Sync).

Exclusively locks the database file for its lifetime.

Implementations

impl Database

pub fn sql_cache_get<T: Any + Send + Sync>(&self, key: &str) -> Option<Arc<T>>

Fetch a typed entry from the shared SQL cache. Returns None if the key is missing or stored under a different type.

pub fn sql_cache_insert<T: Any + Send + Sync>(&self, key: String, value: Arc<T>)

Insert (or overwrite) a typed entry in the shared SQL cache.

pub fn sql_cache_invalidate_prefix(&self, prefix: &str) -> usize

Remove every entry whose key starts with prefix. Returns the number of entries removed.

pub fn sql_cache_len(&self) -> usize

Total number of cache entries (test/diagnostics helper).

pub fn sql_cache_handle(&self) -> SqlCacheHandle

Cloneable handle to the shared cache.

pub fn begin_read(&self) -> ReadTxn<'_>

Begin a read-only transaction with snapshot isolation.

pub fn begin_write(&self) -> Result<WriteTxn<'_>>

Begin a read-write transaction. Only one can be active at a time.

pub fn stats(&self) -> DbStats

Get database statistics from the current commit slot.

pub fn data_path(&self) -> &Path

pub fn key_path(&self) -> &Path

pub fn file_id(&self) -> u64

Database file identifier from the file header. citadel-mem binds the region key store to this value so a mismatched sidecar is rejected.

pub fn region_keys_enabled(&self) -> bool

Whether per-region cryptographic erasure keys are available. true only when the database was opened with enable_region_keys(true).

pub fn wrap_region_key(&self, rck: &[u8; 32]) -> Result<[u8; 40]>

Wrap a region’s random content key (RCK) under the region KEK (AES-256-KW). The 40-byte result is the sole copy of the RCK; citadel-mem stores it in the sidecar key store and overwrites it in place to erase the region.

pub fn unwrap_region_key(&self, wrapped: &[u8; 40]) -> Result<[u8; 32]>

Unwrap a region content key. Fails if the slot was erased (zeroed wrap).

pub fn region_store_mac_key(&self) -> Result<[u8; 32]>

HMAC key authenticating the region key store’s header and slots (torn-write detection only; RCK secrecy is protected by AES-KW).

pub fn region_store_path(&self) -> PathBuf

Path to the sidecar region key store, {key_path} with the citadel-regions extension. Pure path math; valid even when region keys are disabled (the file only exists once an encrypted region is created).

pub fn region_store_allocate_write( &self, region_id: u64, wrapped: &[u8; 40], ) -> Result<(u32, u64)>

Allocate a slot and store the wrapped RCK (fsync’d); returns (slot, gen).

pub fn region_store_slot(&self, slot: u32) -> Result<SlotRecord>

The authoritative record of region key slot.

pub fn region_store_tombstone(&self, slot: u32, region_id: u64) -> Result<()>

Cryptographically erase region key slot (no-op if already erased).

pub fn region_store_live_owners(&self) -> Result<Vec<(u32, u64)>>

(slot, region_id) for every LIVE region key slot.

pub fn atom_store_path(&self) -> PathBuf

Path to the sidecar per-atom key store, {key_path} with the citadel-atomkeys extension. Pure path math; the file only exists once an encrypted atom is written.

pub fn atom_store_allocate_write( &self, atom_id: u64, wrapped: &[u8; 40], ) -> Result<(u32, u64)>

Allocate a slot and store one atom’s wrapped ACK (fsync’d); returns (slot, gen).

pub fn atom_store_allocate_batch( &self, items: &[(u64, [u8; 40])], ) -> Result<Vec<(u32, u64)>>

Allocate and durably write a batch of (atom_id, wrapped) ACKs with ONE fsync; returns (slot, gen) per item in order.

pub fn atom_store_slot(&self, slot: u32) -> Result<SlotRecord>

The authoritative record of atom key slot (its wrapped ACK and state).

pub fn atom_store_tombstone(&self, slot: u32, atom_id: u64) -> Result<()>

Cryptographically erase atom key slot (no-op if already erased).

pub fn atom_store_tombstone_batch(&self, items: &[(u32, u64)]) -> Result<()>

Erase a batch of atom key slots with two fsyncs total (not 2N). Items are (slot, atom_id).

pub fn atom_store_live_wrapped(&self) -> Result<FxHashMap<u64, [u8; 40]>>

Every LIVE atom key’s atom_id -> wrapped ACK, in one whole-file pass.

pub fn atom_store_live_owners(&self) -> Result<Vec<(u32, u64)>>

(slot, atom_id) for every LIVE atom key slot.

pub fn reader_count(&self) -> usize

Number of currently active readers.

pub fn change_passphrase( &self, old_passphrase: &[u8], new_passphrase: &[u8], ) -> Result<()>

Change the database passphrase (re-wraps REK, no page re-encryption).

pub fn integrity_check(&self) -> Result<IntegrityReport>

pub fn backup(&self, dest_path: &Path) -> Result<()>

Create a hot backup via MVCC snapshot. Also copies the key file.

pub fn export_key_backup( &self, db_passphrase: &[u8], backup_passphrase: &[u8], dest_path: &Path, ) -> Result<()>

Export an encrypted key backup for disaster recovery.

Requires the current database passphrase. The backup can later restore access via restore_key_from_backup if the database passphrase is lost.

pub fn restore_key_from_backup( backup_path: &Path, backup_passphrase: &[u8], new_db_passphrase: &[u8], db_path: &Path, ) -> Result<()>

Restore a key file from an encrypted backup (static - no Database needed).

Unwraps the REK using backup_passphrase, then creates a new key file protected by new_db_passphrase.

pub fn compact(&self, dest_path: &Path) -> Result<()>

Compact the database into a new file. Also copies the key file.

impl Database

pub fn audit_log_path(&self) -> Option<PathBuf>

Path to the audit log file, if audit logging is enabled.

pub fn verify_audit_log(&self) -> Result<AuditVerifyResult>

Verify the audit log’s HMAC chain integrity.

impl Database

pub fn node_id(&self) -> Result<NodeId>

Get or create a persistent NodeId for this database.

pub fn sync_to(&self, addr: &str, sync_key: &SyncKey) -> Result<SyncOutcome>

Push local named tables to a remote peer.

pub fn handle_sync( &self, stream: TcpStream, sync_key: &SyncKey, ) -> Result<SyncOutcome>

Handle an incoming sync session from a remote peer.

Trait Implementations

impl Debug for Database

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Database

Available on crate feature audit-log only.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for Database

impl Sync for Database