Struct Engine 

pub struct Engine {
    pub(crate) db: DBWithThreadMode<MultiThreaded>,
    pub(crate) pool: Arc<Pool>,
    pub(crate) ctx: Arc<Context>,
    pub(crate) read_only: bool,
    pub(crate) secondary: bool,
    pub(crate) checksums: bool,
    pub(crate) write_options: WriteOptions,
    cf_index: OnceLock<BTreeMap<u32, Weak<Map>>>,
    corks: AtomicU32,
}

Handle to the opened RocksDB database and its shared resources.

One Engine exists per database, shared behind an Arc by every Map.

Fields

db: DBWithThreadMode<MultiThreaded>

The opened RocksDB instance.

pool: Arc<Pool>

Thread pool offloading uncached, blocking database requests from the tokio workers.

ctx: Arc<Context>

Resources constructed before the database is opened and outliving it (block caches, environment, column descriptors).

read_only: bool

Database was opened read-only; writes are rejected.

secondary: bool

Database was opened as a secondary follower of a primary instance.

checksums: bool

Verify block checksums on read.

write_options: WriteOptions

Shared write options for atomic batch commits.

cf_index: OnceLock<BTreeMap<u32, Weak<Map>>>

Resolves catalog column ids for post-commit watcher notification. Runtime migration column families are intentionally absent.

corks: AtomicU32

Live cork count; nonzero suppresses the per-write WAL flush.

Implementations

impl Engine

pub fn backup(&self) -> Result

Creates a RocksDB backup of the current database.

Writable engines flush before snapshotting, while read-only engines back up their current view without a flush. Old backups are then purged to the configured retention count; a purge failure is logged without failing the newly created backup.

Panics

Panics if RocksDB reports successful creation without returning metadata for the new backup.

impl Engine

pub fn backup_purge(&self, keep: usize) -> Result

Deletes old backups while retaining the newest keep entries.

Passing zero removes every backup known to the backup engine. Retention and deletion are delegated to RocksDB’s backup repository.

impl Engine

pub fn backup_list(&self) -> Result<impl Iterator<Item = String> + Send>

Lists available backups as human-readable summary lines.

Each line includes the backup identifier, timestamp, byte size, and file count. An empty backup repository returns an error instead of an empty iterator.

impl Engine

pub fn backup_count(&self) -> Result<usize>

Returns the number of backups currently recorded.

The count comes from RocksDB’s backup metadata. An empty repository produces zero.

impl Engine

pub fn backup_verify(&self, backup_id: u32) -> Result<u32>

Verifies the integrity of a RocksDB backup.

Identifier zero selects the most recent backup; any other identifier selects that exact entry. The verified backup identifier is returned on success.

impl Engine

pub fn file_list(&self) -> impl Iterator<Item = Result<SstFile>> + Send + use<>

Lists the live SST files belonging to this database.

RocksDB produces the inventory before the iterator is returned. Each yielded entry describes one table file from that in-memory inventory.

impl Engine

pub fn memory_usage(&self) -> Result<String>

Formats the database engine’s current memory usage.

The report covers memtables, pending writes, table readers, and the row cache. When column-cache pools exist, it also includes their usage, capacity, pinned memory, and participating column-family counts.

impl Engine

fn write_pool(&self, out: &mut String, name: &str, pool: &ColCache) -> Result

impl Engine

pub(crate) async fn open( ctx: Arc<Context>, desc: &[Descriptor], ) -> Result<Arc<Self>>

impl Engine

fn configure_cfds( ctx: &Arc<Context>, db_opts: &Options, desc: &[Descriptor], ) -> Result<(Vec<ColumnFamilyDescriptor>, Vec<String>)>

impl Engine

fn discover_cfs(path: &Path, opts: &Options) -> Result<BTreeSet<String>>

impl Engine

pub fn wait_compactions_blocking(&self) -> Result

Block until outstanding background compactions finish.

Waits without a timeout and does not flush first; aborts the wait if compaction has been paused.

pub fn sort(&self) -> Result

Flush the memtables to SST files (a RocksDB LSM-tree flush).

Forces buffered writes out of memory into the on-disk LSM tree. An LSM flush, not a libc fflush(3) or fsync(2), and distinct from the flush and sync methods here, which act on the write-ahead log.

pub fn update(&self) -> Result

Catch a secondary instance up to the primary’s latest writes.

Replays the primary’s newly appended WAL into this instance’s view; meaningful only when the database was opened as a secondary.

pub fn sync(&self) -> Result

Flush the write-ahead log and fsync it to disk.

Once this returns the buffered writes survive power loss. Heavier than flush, which stops at the OS page cache.

pub fn flush(&self) -> Result

Flush the buffered write-ahead log to the OS without an fsync.

Pushes WAL bytes to the page cache (durable against process crash, not power loss). This is the per-write flush that corking suppresses.

pub(crate) fn cork(&self)

Increment the cork count, suppressing the per-write WAL flush.

pub(crate) fn uncork(&self)

Decrement the cork count; the per-write flush resumes at zero.

pub fn corked(&self) -> bool

Whether any cork is currently held.

When true, Map insert and remove skip their post-write WAL flush so the records coalesce into one batch. Corking is purely a backend write-buffering signal: it never changes application logic or any observable database API behavior, because a write lands in the memtable synchronously and reads back regardless of WAL flush state. See the cork module.

pub(crate) fn property_integer( &self, cf: &impl AsColumnFamilyRef, name: &CStr, ) -> Result<u64>

Query for database property by null-terminated name which is expected to have a result with an integer representation. This is intended for low-overhead programmatic use.

pub(crate) fn property( &self, cf: &impl AsColumnFamilyRef, name: &str, ) -> Result<String>

Query for database property by name receiving the result in a string.

pub(crate) fn cf(&self, name: &str) -> Arc<BoundColumnFamily<'_>>

Look up a column-family handle by name.

The handle refers to a family opened with this database and remains tied to the engine’s lifetime.

Panics

Panics if the family was not described before the database was opened.

pub fn has_cf(&self, name: &str) -> bool

Reports whether a column family with this name exists.

The lookup consults the handles currently opened by RocksDB. It does not create a missing family.

pub fn current_sequence(&self) -> u64

Returns the latest RocksDB sequence number.

RocksDB assigns sequence numbers to committed writes, so this value marks the engine’s current write position. The number is local to this database.

pub fn is_read_only(&self) -> bool

Reports whether this engine rejects writes.

Both read-only and secondary opens reject writes through their database handle. A writable primary open returns false.

pub fn is_secondary(&self) -> bool

Reports whether the database follows a primary as a secondary.

A secondary advances its view when Self::update catches up with the primary. Writes through the secondary handle are rejected.

impl Engine

pub(crate) fn set_cf_index(&self, index: BTreeMap<u32, Weak<Map>>)

impl Engine

pub(crate) fn map_by_cf_id(&self, cf_id: u32) -> Option<Arc<Map>>

Trait Implementations

impl Drop for Engine

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.