Crate regolith 

Regolith: ACID, performance oriented, embedded key-value database engine for edge systems.

Regolith provides a fast, embedded key-value store with:

• Read committed, snapshot isolation, or serializable per transaction, via MVCC sequence numbers
• Lock-free transactions whose reads and writes take &self, so one transaction can be shared across threads without a lock
• Crash recovery via write-ahead logging (WAL)
• LZ4 compression for data blocks
• Bloom filters for fast negative lookups
• Level-based compaction on a dedicated OS thread
• Lock-free reads via an arena-backed skip list memtable
• Zero-copy reads via DbSlice, which borrows the bytes the database already holds

Quick Start

use regolith::{Db, Options};

let db = Db::open("/tmp/my_db", Options::default()).unwrap();

// Write
db.put(b"hello", b"world").unwrap();

// Read
let value = db.get(b"hello").unwrap();
assert_eq!(value, Some(b"world".to_vec()));

// Delete
db.delete(b"hello").unwrap();

// Batch write
let mut batch = regolith::WriteBatch::new();
batch.put(b"key1", b"val1");
batch.put(b"key2", b"val2");
batch.delete(b"key3");
db.write(batch).unwrap();

// Snapshot reads
let snap = db.snapshot();
db.put(b"key1", b"val_new").unwrap();
// Snapshot still sees old value
assert_eq!(snap.get(b"key1").unwrap(), Some(b"val1".to_vec()));

Re-exports

pub use env::Capabilities;

pub use env::Env;

pub use env::MemEnv;

pub use env::StdEnv;

Modules

env

The host platform, behind one trait.

Structs

ArenaProfile

How a memtable arena sizes its chunks.

BackupEngine

Content-addressed backup repository for one or more databases.

BackupId

Opaque identifier for a single backup generation. Monotonically increasing within a backup directory.

BackupInfo

High-level summary of a backup returned from BackupEngine::list_backups.

CfIter

Streaming iterator scoped to a single column family. Wraps a regular Iter and bounds the scan to the CF’s prefix range, stripping the 4-byte CF prefix from every key before returning it. Created by Db::iter_cf / Snapshot::iter_cf.

Checkpoint

A handle to a Db prepared for checkpointing. The handle itself captures no engine state - the actual flush, version snapshot, and filesystem work all happen inside Checkpoint::create under a single held compaction lock, so dropping the Checkpoint without calling create is free.

ColumnFamilyHandle

A handle to a column family. Cheap to clone; carries only the CF’s name and numeric id. Handles become invalid after their CF is dropped; result-returning CF operations reject stale handles.

CompactionJobInfo

Information about a compaction job, passed to EventListener::on_compaction_begin and EventListener::on_compaction_completed.

Db

A key-value database backed by an LSM-tree.

DbSlice

A borrowed, refcounted view of a value.

DbWithTtl

A Db wrapper that attaches a wall-clock TTL to every written value. Entries whose embedded timestamp is older than ttl_seconds read as None and are physically reclaimed at the next compaction.

Entries

Ordered entries drained from a cursor, from its current position on.

ExternalFileIngestionInfo

Information about a file ingested via crate::Db::ingest_external_files.

FifoCompactionOptions

Tunables for CompactionStyle::Fifo. Ignored when Options::compaction_style is CompactionStyle::Level.

FixedLengthPrefix

A PrefixExtractor that takes the first N bytes of every key. Keys shorter than N contribute no prefix.

FlushJobInfo

Information about a flush that just completed.

HistogramSnapshot

Immutable snapshot of a single histogram’s state. Callers read this to export to their metrics pipeline or assert in tests.

IngestOptions

Options controlling how crate::Db::ingest_external_files moves files into the database.

Iter

Streaming iterator over a consistent view of the database.

MemTableStats

Approximate memtable stats returned by Db::get_approximate_memtable_stats. count is the number of raw entries (including every version and every tombstone) for user keys in the queried range; size is the sum of internal_key.len() + value.len() over those entries. Both values are exact with respect to the current active memtable - this method walks the skip list.

OptimisticTransactionDb

Optimistic-concurrency-control wrapper over a Db.

Options

Configuration options for a regolith database.

OwnedSnapshotIter

Owned streaming iterator over a Snapshot in the default column family. This is useful for adapters that need to return an owned iterator object without tying the type to a borrowed snapshot lifetime.

OwnedTransaction

A Transaction bundled with an owning handle on the database that began it.

PerfContext

Thread-local performance counters. See the module docs for the usage pattern; every accessor is a static function so callers never need a live reference.

PerfContextSnapshot

Immutable snapshot of the current thread’s perf counters. Returned by PerfContext::capture so callers can inspect fields without holding the live thread-local borrow.

Range

A half-open key range [start, end) passed to the approximate-size APIs. Borrowed; cheap to construct inline.

ScanPage

One bounded page of ordered scan results.

ScanStream

A lazy, bounded scan over a key range.

Snapshot

A point-in-time snapshot for consistent reads.

SstFileMeta

Summary of a finished ingest file, returned by SstFileWriter::finish.

SstFileWriter

Writes a standalone SSTable file that a running crate::Db can bulk-ingest via crate::Db::ingest_external_files.

Statistics

Engine-wide counters and histograms. Constructed by the caller and passed to crate::Options::statistics. The engine clones the Arc into the paths it wants to instrument and updates it via lock-free atomic adds (tickers) or short mutex sections (histograms).

StreamOptions

How a StreamingWriter buffers.

StreamingWriter

A write stream that bounds its own memory.

TableFileCreationInfo

Information about a freshly-created SSTable file. Fires for both flush output and compaction output, distinguished by TableFileCreationReason.

TableFileDeletionInfo

Information about an SSTable file that was just unlinked from disk. Fires after compaction has committed the version edit that removed the file from the live set and the physical unlink(2) has succeeded.

TailingIter

Forward-only tailing iterator. See the module docs.

TokenBucketRateLimiter

Default rate-limiter implementation: a single token bucket refilled at bytes_per_second bytes/sec with a burst capacity of burst_bytes.

Transaction

An in-flight transaction. Created by OptimisticTransactionDb::begin_transaction or TransactionDb::begin_transaction and resolved by Transaction::commit or Transaction::rollback.

TransactionDb

Pessimistic-concurrency-control wrapper over a Db.

TtlCompactionFilter

Compaction filter that drops every point entry whose embedded Unix timestamp is older than ttl_seconds at compaction time.

TxnScanStream

A transaction’s view of a key range, streamed.

UniversalCompactionOptions

Tunables for CompactionStyle::Universal. Ignored when the style is not CompactionStyle::Universal.

WalFullInfo

Information about a full WAL. The struct is declared so that listener implementations can target a common shape across storage backends; regolith itself never fires this callback, because the engine rotates the WAL alongside every memtable and there is no separate “WAL-full” condition.

WriteBatch

A batch of write operations to apply atomically.

WriteOptions

Per-call knobs for point and batch writes. Overrides the database- global Options::durability on a single operation so callers can opt a critical write into synchronous fsync, or opt a bulk-load phase out of the WAL, without flipping the whole database.

Enums

BackgroundErrorReason

Reason passed to EventListener::on_background_error.

CompactionDecision

Decision returned by a CompactionFilter for each entry it sees.

CompactionStyle

Compaction strategy used by the background compaction thread.

CompressionType

Block compression codec applied to SSTable data blocks.

DurabilityMode

Controls when data is flushed to disk after a write.

Error

Errors returned by regolith operations.

Histogram

Enumerated histograms recorded by the engine. Every variant is backed by one histogram slot in Statistics, guarded by its own short mutex so recording is non-contending across histograms.

IsolationLevel

How much a transaction is protected against concurrent commits.

PerfLevel

Granularity of PerfContext measurement. Higher levels produce more detail at the cost of more work per instrumentation site.

Priority

Priority of a rate-limited I/O request. High-priority waiters are always served before low-priority waiters; within a priority class waiters are served in FIFO order.

ScanDirection

Which way a scan walks its range.

TableFileCreationReason

Why the flush / compaction path chose to produce a file, used by TableFileCreationInfo::reason.

Ticker

Enumerated counters incremented by the engine. Every variant is backed by one AtomicU64 slot in Statistics; looking up a ticker is O(1) and thread-safe.

TransactionError

Reasons a transaction can fail to commit. Not a variant of crate::Error: a conflict is a retry-able business outcome, distinct from an I/O failure.

Constants

DEFAULT_CF_NAME

Name of the default column family.

DEFAULT_MAX_BACKGROUND_COMPACTIONS

Default value of Options::max_background_compactions: one background worker, or none on a target that has no threads.

DEFAULT_MAX_KEY_SIZE

Default maximum user-key length accepted by write APIs: 8 MiB.

DEFAULT_MAX_VALUE_SIZE

Default maximum value / merge-operand length accepted by write APIs: 64 MiB.

DEFAULT_TRANSACTION_KEYS_INLINE

Default Options::transaction_keys_inline.

MAX_BLOCK_CACHE_SHARD_BITS

Highest supported block-cache shard exponent.

MAX_BLOOM_BITS_PER_KEY

Highest supported Bloom-filter density. Larger values waste space because the hash count is already capped internally.

Traits

CompactionFilter

A user-supplied hook that runs during compaction and can drop or rewrite entries in place. Typical uses: TTL expiration, application- level GC, schema migrations.

EventListener

Trait implemented by callers that want to react to engine lifecycle events. Registered via crate::Options::listeners.

MergeOperator

A user-supplied associative merge operator.

PrefixExtractor

Carves a prefix out of a user key so the SSTable bloom filter can answer “does this file contain any key with prefix P?” queries.

RateLimiter

A byte-denominated rate limiter.

Functions

strip_timestamp

Return the raw user value with the trailing TTL suffix removed. Returns None if stamped does not contain a supported suffix. Callers that hold a stamped buffer from a raw read through DbWithTtl::inner can use this to recover the user payload.

Type Aliases

Result

Result type for regolith operations.

TxResult

Convenience alias for results returned by transaction methods.