Struct DatabaseBuilder 

pub struct DatabaseBuilder { /* private fields */ }

Builder for creating or opening a Citadel database.

Examples

use citadel::{DatabaseBuilder, Argon2Profile};

let db = DatabaseBuilder::new("mydb.citadel")
    .passphrase(b"secret")
    .cache_size(512)
    .create()
    .unwrap();

Implementations

impl DatabaseBuilder

pub fn new(path: impl Into<PathBuf>) -> Self

pub fn passphrase(self, passphrase: &[u8]) -> Self

pub fn key_path(self, path: impl Into<PathBuf>) -> Self

pub fn argon2_profile(self, profile: Argon2Profile) -> Self

pub fn cache_size(self, pages: usize) -> Self

pub fn cipher(self, cipher: CipherId) -> Self

pub fn kdf_algorithm(self, algorithm: KdfAlgorithm) -> Self

Set the key derivation function algorithm.

Default: Argon2id. Use Pbkdf2HmacSha256 for FIPS 140-3 compliance. When using PBKDF2, the Argon2 profile is ignored and iterations are controlled by pbkdf2_iterations().

pub fn pbkdf2_iterations(self, iterations: u32) -> Self

Set the number of PBKDF2 iterations (only used when KDF is PBKDF2).

Default: 600,000 (OWASP 2024 minimum for PBKDF2-HMAC-SHA256).

pub fn sync_mode(self, mode: SyncMode) -> Self

pub fn enable_region_keys(self, enable: bool) -> Self

Enable per-region cryptographic erasure (used by citadel-mem).

When set, a region wrap key is derived from the REK at create/open and retained for the database lifetime so encrypted memory regions can be sealed under random per-region keys and erased on forget. Off by default; the plaintext storage path is unaffected either way.

pub fn enable_secure_delete(self, enable: bool) -> Self

Zero-fill freed B+ tree pages once they are past all readers, so a passphrase holder with disk access cannot recover deleted-row residue from stale pages. Off by default (a small write cost on delete-heavy workloads).

pub fn audit_config(self, config: AuditConfig) -> Self

Configure the audit log.

Default: enabled with 10 MB max file size and 3 rotated files.

pub fn create(self) -> Result<Database>

Create a new database. Fails if the data file already exists.

pub fn create_in_memory(self) -> Result<Database>

Create a new in-memory database (volatile, no file I/O).

Data exists only for the lifetime of the returned Database. Useful for testing, caching, and WASM environments.

pub fn open(self) -> Result<Database>

Open an existing database. Fails if the data file does not exist.