Struct Db 

pub struct Db { /* private fields */ }

The main database handle.

Provides a high-level, thread-safe API for reading and writing key-value pairs with automatic background flushing and compaction.

Thread safety

Db is Send + Sync — it can be shared across threads via Arc<Db>.

Background compaction

When the write buffer fills, the active memtable is frozen and a background task is dispatched to:

1. Flush the frozen memtable to a new SSTable.
2. Run minor compaction if size-tiered thresholds are met.
3. Run tombstone compaction if the tombstone ratio is high enough.

Major compaction must be triggered explicitly via Db::major_compact.

Shutdown

Call Db::close for a graceful shutdown. If the handle is dropped without calling close, the destructor will attempt cleanup, but errors are silently ignored.

Implementations

impl Db

pub fn open(path: impl AsRef<Path>, config: DbConfig) -> Result<Self, DbError>

Opens (or creates) a database at the given directory.

On a fresh directory the required sub-directories are created automatically. On an existing directory, the manifest and WALs are replayed to recover the last durable state.

Errors

• DbError::InvalidConfig — a configuration parameter is out of its documented bounds.
• DbError::Engine — the directory could not be created, the manifest/WAL could not be opened or replayed, or I/O failed during recovery.

pub fn close(&self) -> Result<(), DbError>

Gracefully shuts down the database.

Waits for all in-flight background tasks to complete, flushes remaining frozen memtables, checkpoints the manifest, and fsyncs all directories.

Subsequent operations on this handle return DbError::Closed. Calling close more than once is harmless.

Errors

• DbError::Engine — flush or manifest checkpoint failed during shutdown.

pub fn put(&self, key: &[u8], value: &[u8]) -> Result<(), DbError>

Inserts or updates a key-value pair.

The write is persisted to the WAL before being applied in memory. If the write buffer is full, the active memtable is frozen and a background flush is scheduled automatically.

Errors

• DbError::Closed — the database has been closed.
• DbError::InvalidArgument — key or value is empty.
• DbError::Engine — WAL write or memtable operation failed.

pub fn delete(&self, key: &[u8]) -> Result<(), DbError>

Deletes a key by inserting a point tombstone.

Subsequent reads return None until a new value is written.

Errors

• DbError::Closed — the database has been closed.
• DbError::InvalidArgument — key is empty.
• DbError::Engine — WAL write or memtable operation failed.

pub fn delete_range(&self, start: &[u8], end: &[u8]) -> Result<(), DbError>

Deletes all keys in the half-open range [start, end).

Errors

• DbError::Closed — the database has been closed.
• DbError::InvalidArgument — start or end is empty, or start >= end.
• DbError::Engine — WAL write or memtable operation failed.

pub fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, DbError>

Retrieves the value associated with a key.

Returns Ok(None) if the key does not exist or has been deleted.

Errors

• DbError::Closed — the database has been closed.
• DbError::InvalidArgument — key is empty.
• DbError::Engine — SSTable read or I/O failed.

pub fn scan(&self, start: &[u8], end: &[u8]) -> Result<Vec<KeyValue>, DbError>

Scans all live key-value pairs in the half-open range [start, end).

Returns pairs sorted by key in ascending order. Deleted keys are excluded.

Returns an empty Vec if the range contains no live keys.

Errors

• DbError::Closed — the database has been closed.
• DbError::InvalidArgument — start or end is empty.
• DbError::Engine — SSTable read or I/O failed.

pub fn major_compact(&self) -> Result<bool, DbError>

Runs a full major compaction, merging all SSTables into one.

This is a blocking operation. All range tombstones are applied and all spent tombstones are dropped from the output.

Returns true if compaction was performed, false if there were fewer than 2 SSTables.

Errors

• DbError::Closed — the database has been closed.
• DbError::Engine — SSTable merge, manifest update, or I/O failed during compaction.

Trait Implementations

impl Debug for Db

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

Formats the value using the given formatter.

impl Drop for Db

fn drop(&mut self)

Executes the destructor for this type.