Struct Options 

#[non_exhaustive]
pub struct Options {
    pub cache_max_bytes: u64,
    pub spillway_max_bytes: u64,
    pub drain_insertion: DrainInsertion,
    pub create_if_missing: bool,
    pub read_only: bool,
    pub superblock_count: u32,
    pub encryption_key: Option<Key>,
    pub argon2_params: Option<Argon2Params>,
}

Open-time options. These are consumed once during Chisel::open and not retained on the live handle; changing them later requires reopening.

cache_max_bytes is a strict upper bound on the in-memory page cache, in bytes. Internally converted to a page count via bytes / PAGE_SIZE (rounded down, clamped to at least one page). Replaces the previous cache_size: usize (page count) field; bytes are user-friendly because callers think in MB/GB, not 8KB units. Default 8 MiB = 1024 pages (matches the previous default).

spillway_max_bytes is a strict upper bound on the spillway’s LIVE resident set, in bytes (excluding per-slot 16-byte headers). When the cache is full and dirty, overflow dirty pages are written to the spillway rather than aborting; exceeding this limit (live spilled pages × PAGE_SIZE) trips ChiselError::SpillwayFull. The cap is charged against LIVE residency, not cumulative spill volume: a page read back and respilled within a transaction does not count twice, so the limit is predictable for long transactions. The physical sidecar FILE may transiently grow past this cap (the write cursor is monotonic within a transaction); that tail is reclaimed when the spillway is truncated at commit/rollback. Default 1024 * cache_max_bytes (8 GiB at the default cache size). Setting to 0 disables the spillway entirely — overflow then trips ChiselError::CacheFull at the strict cache cap, with no 8× elasticity (the previous HARD_CEILING_MULTIPLIER is removed).

drain_insertion controls where commit-drain rehydrated pages land in the LRU. LruTail (default) makes them first eviction candidates after commit, preserving the pre-transaction warm working set; Mru treats them as just-touched. See spec §“Drain insertion policy”.

read_only still takes an exclusive flock — it only suppresses writes at the application layer.

superblock_count (ISSUES.md R4) controls how many superblock slots a freshly-created database uses. Default 2 (matches the original layout); valid range is 2..=16. Higher N trades disk space (N × 8 KB) for resilience against consecutive torn writes — N=3 survives one torn commit followed by a torn retry, N=4 survives two retries. This option is ONLY consulted when creating a new database; reopening an existing file discovers N from the on-disk superblock itself. I36 (ISSUES.md, 2026-05-22): #[non_exhaustive] so adding a future field (a tuning knob for cache warmup, an fsync-coalescing hint, etc.) is not a breaking change. External callers must construct via Options { ..Options::default() } rather than a full struct literal; Default is implemented below.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

cache_max_bytes: u64

spillway_max_bytes: u64

drain_insertion: DrainInsertion

create_if_missing: bool

read_only: bool

superblock_count: u32

encryption_key: Option<Key>

Encryption key for an encrypted database. None (default) opens or creates a plaintext DB. On create, Some(key) makes a new encrypted DB sealed under a random DEK wrapped by this key. On reopen, the key must unwrap one of the on-disk key slots or open returns InvalidEncryptionKey. Supplying a key to open a plaintext DB returns EncryptionNotSupported; omitting it on an encrypted DB returns NoEncryptionKey.

argon2_params: Option<Argon2Params>

Argon2id cost parameters used to derive the KEK from a Key::Passphrase on create. None uses Argon2Params::default() (OWASP: 19 MiB / t=2 / p=1). Ignored for Key::Raw (HKDF, no cost params) and on reopen (the params are read from the key slot the file was written with).

Implementations

impl Options

pub fn cache_max_bytes(self, bytes: u64) -> Self

pub fn spillway_max_bytes(self, bytes: u64) -> Self

pub fn drain_insertion(self, policy: DrainInsertion) -> Self

pub fn create_if_missing(self, create: bool) -> Self

pub fn read_only(self, read_only: bool) -> Self

pub fn superblock_count(self, count: u32) -> Self

Set the number of superblock slots. Valid range is 2..=16; any other value is accepted here and rejected at open time with ChiselError::InvalidSuperblockCount. This is only consulted on initial file creation; existing files use the count baked into their header.

pub fn encryption_key(self, key: Key) -> Self

Set the encryption key. On create, a fresh DEK is generated and wrapped into key-slot 0 under a KEK derived from this key; the superblock is stamped MAJOR=2. On open, the key is used to unwrap the stored DEK from the matching slot. See Options::encryption_key for the full create-vs-reopen semantics.

pub fn argon2_params(self, params: Argon2Params) -> Self

Set the Argon2id cost parameters used when deriving a KEK from a passphrase on database creation. No effect for raw keys or on reopen (the stored slot carries its own params). See Options::argon2_params.

Trait Implementations

impl Clone for Options

fn clone(&self) -> Options

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Options

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

Formats the value using the given formatter.

impl Default for Options

fn default() -> Options

Returns the “default value” for a type.