Struct DBOptions 

pub struct DBOptions {

    pub memtable_capacity: usize,
    pub wal_sync_policy: SyncPolicy,
    pub recovery_mode: RecoveryMode,
    pub base_level_size: u64,
    pub size_ratio: u64,
    pub num_levels: usize,
    pub vlog_threshold: Option<usize>,
    pub background_compaction: bool,
    pub background_flush: bool,
    pub adaptive_compaction: bool,
    pub max_memory_bytes: Option<usize>,
    pub min_disk_space_bytes: Option<u64>,
    pub max_open_files: Option<usize>,
    pub block_cache_capacity: usize,
    pub buffer_pool_capacity: Option<usize>,
    pub group_commit_delay_us: u64,
    pub group_commit_max_batch_size: usize,
    pub l0_slowdown_writes_trigger: usize,
    pub l0_stop_writes_trigger: usize,
    pub compaction_filter: Option<Arc<dyn CompactionFilter>>,
    pub merge_operator: Option<Arc<dyn MergeOperator>>,
    pub disable_metrics: bool,
    pub use_direct_wal: bool,
    pub skip_wal: bool,
    pub compression: CompressionType,
    /* private fields */
}

Database configuration options.

Use the builder pattern to configure options, then call open() to create the database. For simple cases, use DB::open().

Quick Start

use seerdb::DBOptions;

// Simple: just open with defaults (recommended for most cases)
let db = seerdb::DB::open("./my_db")?;

// Custom: tune specific options
let db = DBOptions::default()
    .memtable_capacity(512 * 1024 * 1024)  // 512MB write buffer
    .open("./my_db")?;

Configuration Profiles

For common workloads, use a preset profile:

Profile	Use Case	Memory
default()	General purpose	256 MB
embedded()	CLI tools, mobile, IoT	64 MB
high_throughput()	Write-heavy servers	512 MB
large_scale()	1B+ keys, analytics	1 GB

Option Reference

Essential Options

Most users only need these:

Option	Default	Description
memtable_capacity	256 MB	Write buffer size
sync_policy	SyncData	Durability level (see platform notes)
compression	LZ4	SSTable compression

Tuning Options

For performance optimization:

Option	Default	Description
vlog_threshold	4 KB	Value size for key-value separation
block_cache_capacity	16K blocks	Read cache size
adaptive_compaction	false	Auto-tune compaction
background_compaction	true	Async compaction

Expert Options

Rarely needed, for specific tuning:

Option	Default	Description
l0_slowdown_writes_trigger	20	L0 count before throttling
l0_stop_writes_trigger	36	L0 count before blocking
group_commit_delay_us	0	Batching delay
skip_wal	false	Disable durability

Platform Notes

macOS Performance: The default SyncPolicy::SyncData is ~13x slower on macOS than Linux due to APFS treating fdatasync() like fsync(). If your application can tolerate data loss on power failure (but not app crashes), use Barrier:

use seerdb::{DBOptions, SyncPolicy};

// 13x faster writes on macOS, still survives app crashes
let db = DBOptions::default()
    .sync_policy(SyncPolicy::Barrier)
    .open("./my_db")?;

See SyncPolicy for durability trade-offs.

Fields

memtable_capacity: usize

wal_sync_policy: SyncPolicy

recovery_mode: RecoveryMode

base_level_size: u64

size_ratio: u64

num_levels: usize

vlog_threshold: Option<usize>

background_compaction: bool

background_flush: bool

adaptive_compaction: bool

max_memory_bytes: Option<usize>

min_disk_space_bytes: Option<u64>

max_open_files: Option<usize>

block_cache_capacity: usize

buffer_pool_capacity: Option<usize>

group_commit_delay_us: u64

group_commit_max_batch_size: usize

l0_slowdown_writes_trigger: usize

l0_stop_writes_trigger: usize

compaction_filter: Option<Arc<dyn CompactionFilter>>

merge_operator: Option<Arc<dyn MergeOperator>>

disable_metrics: bool

use_direct_wal: bool

skip_wal: bool

compression: CompressionType

Implementations

impl DBOptions

pub fn new() -> Self

Create a new options builder with default values.

pub fn open(&self, path: impl AsRef<Path>) -> Result<DB>

Open a database with these options at the given path.

This is the primary way to open a configured database. For simple cases with default options, use DB::open() instead.

Options can be reused to open multiple databases with the same configuration:

Examples

use seerdb::DBOptions;

let opts = DBOptions::default()
    .memtable_capacity(128 * 1024 * 1024)
    .background_compaction(true);

let db1 = opts.open("./db1")?;
let db2 = opts.open("./db2")?;  // Reuse same options

pub fn embedded() -> Self

Configuration for memory-constrained embedded applications.

Use when: CLI tools, mobile apps, IoT devices, or single-process apps with limited RAM.

Option	Default	Embedded	Reason
memtable_capacity	256 MB	64 MB	Reduce memory footprint
block_cache_capacity	16K	4K	Fewer cached blocks
background_compaction	true	false	Simpler threading model
background_flush	true	false	Predictable latency
metrics	enabled	disabled	Reduce overhead
direct_wal	false	true	Skip pipelined WAL

pub fn high_throughput() -> Self

Configuration for write-heavy server workloads.

Use when: High-throughput services, streaming data ingestion, or write-heavy OLTP workloads.

Option	Default	High-Throughput	Reason
memtable_capacity	256 MB	512 MB	Larger write buffer, fewer flushes
block_cache_capacity	16K	64K	More cached blocks for reads
adaptive_compaction	false	true	Auto-tune compaction strategy

pub fn large_scale() -> Self

Configuration for large datasets (1B+ keys, 100GB+ data).

Use when: Data warehousing, analytics backends, or any workload where dataset size exceeds available RAM.

Option	Default	Large-Scale	Reason
memtable_capacity	256 MB	1 GB	Batch more writes before flush
block_cache_capacity	16K	128K	Cache more blocks for large scans
base_level_size	10 MB	64 MB	Reduce level count for large data
vlog_threshold	4 KB	1 KB	Separate values earlier (less write amp)
adaptive_compaction	false	true	Auto-tune for varying load

pub const fn memtable_capacity(self, bytes: usize) -> Self

Set the memtable capacity in bytes.

pub const fn block_cache_capacity(self, num_blocks: usize) -> Self

Set the block cache capacity (number of blocks).

pub const fn sync_policy(self, policy: SyncPolicy) -> Self

Set the WAL sync policy.

pub const fn background_compaction(self, enabled: bool) -> Self

Enable or disable background compaction.

pub const fn background_flush(self, enabled: bool) -> Self

Enable or disable background flush.

pub const fn metrics(self, enabled: bool) -> Self

Enable or disable metrics collection.

pub const fn direct_wal(self, enabled: bool) -> Self

Enable or disable direct WAL writes.

pub const fn skip_wal(self, enabled: bool) -> Self

Enable or disable WAL entirely.

pub const fn vlog_threshold(self, threshold: Option<usize>) -> Self

Set the value size threshold for vLog separation.

pub const fn compression(self, compression: CompressionType) -> Self

Set the compression type for SSTables.

pub fn merge_operator(self, operator: Arc<dyn MergeOperator>) -> Self

Set the merge operator for read-modify-write operations.

pub const fn recovery_mode(self, mode: RecoveryMode) -> Self

Set the recovery mode for WAL replay.

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

Set the base level size for LSM compaction (bytes).

pub const fn size_ratio(self, ratio: u64) -> Self

Set the size ratio between LSM levels.

pub const fn num_levels(self, levels: usize) -> Self

Set the number of LSM levels.

pub const fn adaptive_compaction(self, enabled: bool) -> Self

Enable or disable adaptive compaction.

pub const fn max_memory_bytes(self, bytes: Option<usize>) -> Self

Set the maximum memory budget in bytes.

pub const fn min_disk_space_bytes(self, bytes: Option<u64>) -> Self

Set the minimum disk space threshold in bytes.

pub const fn max_open_files(self, max: Option<usize>) -> Self

Set the maximum number of open files.

pub const fn buffer_pool_capacity(self, capacity: Option<usize>) -> Self

Set the buffer pool capacity.

pub const fn group_commit_delay_us(self, us: u64) -> Self

Set the group commit delay in microseconds.

pub const fn group_commit_max_batch_size(self, size: usize) -> Self

Set the maximum batch size for group commits.

pub const fn l0_slowdown_writes_trigger(self, count: usize) -> Self

Set the L0 file count that triggers write slowdown.

pub const fn l0_stop_writes_trigger(self, count: usize) -> Self

Set the L0 file count that stops writes entirely.

pub fn compaction_filter(self, filter: Arc<dyn CompactionFilter>) -> Self

Set a compaction filter for custom key filtering during compaction.

Trait Implementations

impl Clone for DBOptions

fn clone(&self) -> DBOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DBOptions

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

Formats the value using the given formatter.

impl Default for DBOptions

fn default() -> Self

Returns the “default value” for a type.