Struct StorageConfig 

pub struct StorageConfig {

    pub max_sstable_size: u64,
    pub memtable_size_threshold: u64,
    pub compaction: CompactionConfig,
    pub block_size: u32,
    pub compression: CompressionConfig,
    pub enable_bloom_filters: bool,
    pub bloom_filter_fp_rate: f64,
    pub io_threads: usize,
    pub sync_mode: SyncMode,
    pub use_mmap: bool,
    pub mmap_min_size_bytes: usize,
    pub disk_access_mode: DiskAccessMode,
    pub direct_io_memory_fraction: f64,
    pub prefetch: PrefetchMode,
    pub direct_io_prefetch_bytes: usize,
}

Storage engine configuration

Fields

max_sstable_size: u64

Maximum SSTable file size in bytes (default: 64MB)

memtable_size_threshold: u64

MemTable size threshold for flushing (default: 16MB)

compaction: CompactionConfig

Compaction configuration

block_size: u32

Block size for SSTable data blocks (default: 64KB)

compression: CompressionConfig

Compression configuration

enable_bloom_filters: bool

Enable bloom filters for SSTables

bloom_filter_fp_rate: f64

Bloom filter false positive rate (default: 0.01)

io_threads: usize

Number of background threads for I/O operations

sync_mode: SyncMode

Sync mode for durability

use_mmap: bool

Memory-map SSTable Data.db files instead of using buffered file I/O.

Opt-in. Defaults to false (buffered I/O), which is portable and safe on every filesystem. When enabled, the reader maps Data.db files at or above Self::mmap_min_size_bytes into the process address space and serves reads from the OS page cache with no per-block read syscall, mirroring Cassandra’s disk_access_mode: mmap. This speeds up repeated local scans of the same files.

Safety / platform constraints

A memory map aliases the file’s bytes for the reader’s lifetime. Only enable this when the SSTables are immutable local files:

• Mutating, truncating, or deleting a mapped file out from under a live reader is undefined behaviour and can raise SIGBUS, terminating the process. CQLite never rewrites its own mapped inputs, but external tools must not either.
• Network and overlay filesystems (NFS, SMB, FUSE, some container overlays) can fault mid-read after a successful map; prefer buffered I/O there.

Interaction with the write engine (Issue #591)

This setting only affects the read path. Compaction always reads its input SSTables through buffered I/O regardless of use_mmap, and deletes each input by removing its TOC.txt first (unpublishing it) before the data components, best-effort. So enabling mmap for queries is safe alongside background compaction: a compaction never holds a mapping over a file it then deletes, and on Windows a data file still pinned by a mapped reader becomes an invisible orphan (reclaimed on the next startup) rather than a failed delete or a source of duplicate rows.

Can also be enabled at runtime by setting CQLITE_USE_MMAP=1.

#[serde(default)] keeps configs serialized before this field existed (which omit it) deserializing successfully, defaulting to buffered I/O.

mmap_min_size_bytes: usize

Minimum Data.db file size (bytes) before Self::use_mmap takes effect.

Files smaller than this use buffered I/O even when use_mmap is set, since the per-file mapping overhead is not worthwhile for tiny files and mapping a zero-length file is invalid. Defaults to one page (4096).

#[serde(default)] for backward compatibility with older payloads.

disk_access_mode: DiskAccessMode

How the SSTable read path accesses Data.db on disk.

Defaults to DiskAccessMode::Auto, which sizes each Data.db file against system RAM and picks the backend automatically:

• files below Self::mmap_min_size_bytes use buffered I/O (mapping a tiny file is not worth the setup cost);
• files up to Self::direct_io_memory_fraction of system memory are memory-mapped, so repeated scans stay resident in the page cache;
• files larger than that fraction use direct I/O (O_DIRECT on Linux, F_NOCACHE on macOS), which bypasses the page cache so a single huge scan does not evict everything else the host has cached.

Set an explicit DiskAccessMode::Buffered, DiskAccessMode::Mmap, or DiskAccessMode::Direct to override the heuristic. The legacy Self::use_mmap flag still forces mmap when Auto would otherwise pick buffered, for backward compatibility.

Can also be set at runtime via CQLITE_DISK_ACCESS_MODE (auto / buffered / mmap / direct).

direct_io_memory_fraction: f64

Fraction of total system memory above which DiskAccessMode::Auto switches a file from memory-mapped to direct I/O. Defaults to 0.5 (half of RAM). Clamped to (0.0, 1.0]; values outside that range fall back to the default. Ignored when system memory cannot be determined (in which case Auto never escalates to direct I/O).

prefetch: PrefetchMode

Read-ahead / prefetch strategy applied to the chosen backend.

Defaults to PrefetchMode::Auto, which issues no mmap madvise (relying on the kernel’s default read-ahead) and only enables the direct-I/O prefetch window of Self::direct_io_prefetch_bytes. Set PrefetchMode::Off to disable explicit hints (relying only on default kernel read-ahead / single-block direct reads). Can also be set via CQLITE_PREFETCH (off / sequential / willneed / auto).

direct_io_prefetch_bytes: usize

Size in bytes of the read-ahead window used by the direct-I/O backend (and the buffered backend’s reader capacity hint). Rounded up to the I/O alignment. Defaults to 1 MiB. Only takes effect when Self::prefetch is not PrefetchMode::Off.

Trait Implementations

impl Clone for StorageConfig

fn clone(&self) -> StorageConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for StorageConfig

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

Formats the value using the given formatter.

impl Default for StorageConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for StorageConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for StorageConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.