Nethermind.RocksDbBindings

RocksDB bindings

C# bindings for RocksDB.

CPU requirements

Linux and Windows x64 binaries require x86-64-v2 (SSE4.2 and POPCNT), the .NET 11 baseline. macOS x64 binaries require AVX2, available on all Intel Macs supported by macOS 15.

Decoded batched reads

MultiGet<T, TDeserializer> reads contiguous fixed-length keys and writes decoded values into a caller-owned span. The key buffer length must equal keyLength * values.Length. Both class and struct deserializers implement ISpanDeserializer<T>; struct deserializers do not require boxing.

int[] values = new int[keyCount];
db.MultiGet<int, Int32Deserializer>(keys, keyLength, values, default, family);

Missing keys produce default(T) without invoking the deserializer. Empty values still invoke it with an empty span. The native value span is valid only during Deserialize; the deserializer must not retain a pointer to it.

sortedInput: true requires keys already sorted according to the column family's comparator. Results are undefined if this requirement is not met. The method does not sort or validate this hint. Leave it false for unsorted input.

Argument validation occurs before clearing the output. Native batch errors are checked before decoding starts. With a non-default read tier, every family uses scalar reads; a read failure retains the decoded prefix and leaves the tail cleared. Decoder failures also retain the completed prefix. Disposed family handles are rejected before the output is cleared.

The database stays leased through decoding. Read options are leased while native reads are active. Key and output spans must not overlap. Do not mutate options or the key and output buffers during the call. Concurrent callers need separate output buffers and deserializers that support their use pattern.

Async reads

GetAsync and MultiGetAsync follow the results and error handling of Get and MultiGet. Keys are copied during submission. Read options must not be mutated until completion; disposing the database, read options or snapshot defers their native release until outstanding reads finish.

byte[]? value = await db.GetAsync(key);
KeyValuePair<byte[], byte[]?>[] values = await db.MultiGetAsync(keys);

GetAsync<T> accepts the existing ISpanDeserializer<T> and deserializes directly from native memory without copying the value into a managed byte array. For struct deserializers, use GetAsync<T, TDeserializer> to avoid boxing:

int value = await db.GetAsync<int, Int32Deserializer>(key, default);

readonly struct Int32Deserializer : ISpanDeserializer<int>
{
    public int Deserialize(ReadOnlySpan<byte> buffer)
        => System.Buffers.Binary.BinaryPrimitives.ReadInt32LittleEndian(buffer);
}

Missing keys return default(T) without invoking the deserializer. Deserialization runs on a thread-pool thread; shared deserializers must support concurrent calls. The span is valid only during Deserialize. Single reads use pooled completions: consume each returned ValueTask once, or call AsTask() once to share the result.

The API is the same on every platform. Linux builds enable RocksDB's native coroutine reads using Folly and io_uring. Windows, macOS and filesystems without a read executor use RocksDB's synchronous fallback, which can block during submission. DbOptions.SetReadIoExecutorThreads configures the shared executor on supported builds. This API does not cancel submitted reads.

Reusing iterator bounds

ReadOptions.UpdateIterateBounds copies new lower and upper bounds into the buffers reserved by SetIterateBounds. Each new bound must fit its original buffer. Larger bounds and missing buffers are rejected before either bound changes. Updating does not allocate or replace the buffers.

Bounds reuse supports non-tailing iterators only. Updates are rejected while SetTailing(true) is set. Once these options have created a tailing iterator, use fresh non-tailing options for bounds reuse. Setting tailing to false later does not change an existing iterator's mode.

using ReadOptions options = new ReadOptions().SetIterateBounds(firstLower, firstUpper);
using Iterator iterator = db.NewIterator(readOptions: options);

foreach ((byte[] lower, byte[] upper) in ranges)
{
    options.UpdateIterateBounds(lower, upper);
    iterator.Seek(lower);
    while (iterator.Valid())
    {
        Consume(iterator.GetKeySpan(), iterator.GetValueSpan());
        iterator.Next();
    }
    iterator.ThrowIfError();
}

All iterators created from these options observe the new bounds. Stop using them before updating, then seek each iterator again before reading it. Do not update bounds concurrently with iteration or outstanding asynchronous reads. The ordinary SetIterate* methods replace buffers and must not be called while an iterator uses them.

Updating bounds does not refresh the iterator's snapshot. Keep reuse local to a request or other bounded read scope, then dispose the iterator. A long-lived iterator can retain memtables and SST files after compaction.

License

This project is licensed under the MIT license.

Parts of the managed API were originally derived from rocksdb-sharp, used under BSD-2-Clause, and have since been substantially rewritten.

The package also ships prebuilt RocksDB binaries, used under the Apache-2.0 option of RocksDB's dual Apache-2.0/GPL-2.0 license. Those binaries statically link LZ4, Snappy, Zstandard, and, on Linux, jemalloc, Folly and its dependencies.