RocksDb Class

Definition

public class RocksDb : IDisposable

RocksDb is the high-level database handle. It opens a database directory, runs reads and writes, creates iterators, snapshots, and checkpoints, and manages column families. The class wraps the native handle and releases it on Dispose.

Remarks

A RocksDB database is a directory on disk. Obtain a RocksDb from one of the static Open* methods, passing a DbOptions and a path. Always wrap the instance in using so the handle is released and pending writes are flushed when the scope ends.

Read and write methods accept an optional ColumnFamilyHandle, and an optional ReadOptions or WriteOptions. Keys and values can be strings (UTF-8 by default), byte[], or ReadOnlySpan<byte> on net6+.

Methods

Open

public static RocksDb Open(DbOptions options, string path)
public static RocksDb Open(DbOptions options, string path, ColumnFamilies columnFamilies)

Opens a database in read-write (primary) mode. Exactly one process can hold the lock at a time. When the database uses column families, pass a ColumnFamilies that enumerates every existing family.

OpenReadOnly

public static RocksDb OpenReadOnly(DbOptions options, string path, bool errorIfLogFileExists)

Opens the database without taking the write lock, allowing multiple concurrent readers. Set errorIfLogFileExists to true to fail if the WAL has unflushed entries.

OpenAsSecondary

public static RocksDb OpenAsSecondary(DbOptions options, string path, string secondaryPath)

Opens a read-only follower of a primary database. Each secondary needs its own secondaryPath for tail state and can be brought up to date with TryCatchUpWithPrimary.

OpenWithTtl

public static RocksDb OpenWithTtl(DbOptions options, string path, int ttlSeconds)

Opens a database whose keys become eligible for deletion after ttlSeconds. TTL expiry happens during compaction, not at an exact time.

ListColumnFamilies

public static string[] ListColumnFamilies(DbOptions options, string path)

Returns the names of the column families in an existing database. Throws if the database can't be read.

TryListColumnFamilies

public static bool TryListColumnFamilies(DbOptions options, string path, out string[] names)

Non-throwing variant of ListColumnFamilies. Returns false instead of throwing when the families can't be listed.

Put

public void Put(string key, string value, ColumnFamilyHandle cf = null, WriteOptions writeOptions = null)

Inserts or overwrites a key. The write is atomic and visible to all subsequent reads. Overloads accept byte[] and ReadOnlySpan<byte> keys/values.

Get

public string Get(string key, ColumnFamilyHandle cf = null, ReadOptions readOptions = null)
public T Get<T>(byte[] key, ISpanDeserializer<T> deserializer)

Reads a value by key and returns null when the key is missing. The string overload decodes UTF-8 by default. Span and ISpanDeserializer<T> overloads read directly from native memory to avoid allocation.

MultiGet

public KeyValuePair<string, string>[] MultiGet(string[] keys)

Fetches many keys in one call, de-duplicating Bloom-filter and block-cache work across the batch. Missing keys come back with a null value. A byte[][] overload returns KeyValuePair<byte[], byte[]>[].

HasKey

public bool HasKey(string key)

Returns whether a key is present without materialising the value.

Remove

public void Remove(string key, ColumnFamilyHandle cf = null, WriteOptions writeOptions = null)

Deletes a key by writing a tombstone. Removing a missing key is a no-op.

Write

public void Write(WriteBatch batch, WriteOptions writeOptions = null)

Applies a WriteBatch (or WriteBatchWithIndex) as a single atomic write. Either every operation in the batch lands or none do.

NewIterator

public Iterator NewIterator(ColumnFamilyHandle cf = null, ReadOptions readOptions = null)

Creates an ordered Iterator over the database or a single column family. Pass a ReadOptions with a snapshot or iterate bounds to scope the scan. Always dispose the iterator.

CreateSnapshot

public Snapshot CreateSnapshot()

Creates a logical point-in-time Snapshot. Pass it to a ReadOptions via SetSnapshot to read a consistent view. The snapshot implements IDisposable and must be disposed. See Snapshots.

Checkpoint

public Checkpoint Checkpoint()

Creates a Checkpoint object whose Save(path) writes a consistent on-disk copy of the database by hard-linking SST files. See Checkpoints.

GetColumnFamily

public ColumnFamilyHandle GetColumnFamily(string name)

Returns the runtime handle for a named column family.

TryGetColumnFamily

public bool TryGetColumnFamily(string name, out ColumnFamilyHandle cf)

Non-throwing column-family lookup. Returns false when the family is missing.

GetDefaultColumnFamily

public ColumnFamilyHandle GetDefaultColumnFamily()

Returns the handle for the "default" column family that every database has.

CreateColumnFamily

public ColumnFamilyHandle CreateColumnFamily(ColumnFamilyOptions options, string name)

Creates a new column family at runtime and returns its handle.

DropColumnFamily

public void DropColumnFamily(string name)

Drops a column family. RocksDB tombstones the whole family and reclaims space asynchronously during compaction.

TryCatchUpWithPrimary

public void TryCatchUpWithPrimary()

Brings a secondary instance up to date with the writes its primary has made since the last sync. Only valid on instances opened with OpenAsSecondary.

GetProperty

public string GetProperty(string name)

Reads a named RocksDB property, for example rocksdb.stats or rocksdb.estimate-num-keys.

GetLatestSequenceNumber

public ulong GetLatestSequenceNumber()

Returns the engine's monotonically-increasing write counter, useful for pairing with a snapshot to record exactly which state was observed.

GetLiveFileNames

public List<string> GetLiveFileNames()

Lists the active SST files. A related GetLiveFilesMetadata() returns full metadata for each file.

Dispose

public void Dispose()

Closes the database: releases cached column-family handles, calls rocksdb_close (flushing the MemTable and closing the WAL), and suppresses finalization.

Applies to