Quick Start

A five-minute tour of RocksDB-Sharp: open a database, write and read keys, scan with an iterator, batch atomically, take a snapshot, and clean up.

If you haven't already, install the NuGet package:

dotnet add package RocksDb

1. Open a database

RocksDb.Open takes a DbOptions and a directory path. The directory is created for you when CreateIfMissing is true. See the upstream Basic Operations wiki for the engine semantics.

using RocksDbSharp;

var path = Path.Combine(Path.GetTempPath(), "rocksdb-quickstart");

var options = new DbOptions()
    .SetCreateIfMissing(true)
    .IncreaseParallelism(Environment.ProcessorCount);

using var db = RocksDb.Open(options, path);

Always `Dispose`

RocksDb holds an unmanaged handle. Wrap it in using (or call Dispose()) so the database is closed and flushed cleanly.

2. Put, Get, and Remove

Strings are encoded as UTF-8 by default. byte[] and ReadOnlySpan<byte> overloads exist for binary data.

db.Put("user:42", "Ada Lovelace");
string name = db.Get("user:42");        // "Ada Lovelace"

db.Put("counter"u8, BitConverter.GetBytes(1L));
byte[] raw = db.Get("counter"u8.ToArray());

db.Remove("user:42");
bool exists = db.HasKey("user:42");     // false

Read & write reference

3. Scan with an iterator

Iterators walk the keyspace in sorted (byte-wise lexicographic) order. They're the right tool for range scans, prefix matches, or "give me the last N entries".

db.Put("a", "1");
db.Put("b", "2");
db.Put("c", "3");

using var it = db.NewIterator();
for (it.SeekToFirst(); it.Valid(); it.Next())
{
    Console.WriteLine($"{it.StringKey()} = {it.StringValue()}");
}

See the Iterators guide for Seek, SeekForPrev, upper/lower bounds, and reverse scans. Upstream reference: Iterator wiki.

4. Atomic writes with WriteBatch

WriteBatch groups any number of Put/Merge/Delete operations into one atomic write. Either every operation lands, or none do.

using var batch = new WriteBatch();
batch.Put("order:1", "pending");
batch.Put("order:2", "pending");
batch.Delete("draft");

db.Write(batch);

WriteBatch guide

5. Take a snapshot

A snapshot is a point-in-time view of the database. Reads through a snapshot ignore later writes — useful for consistent multi-key reads or long-running scans.

using var snapshot = db.CreateSnapshot();
var readOptions = new ReadOptions().SetSnapshot(snapshot);

db.Put("user:42", "later write");                 // not visible through snapshot

string oldValue = db.Get("user:42", readOptions: readOptions);

Upstream reference: Snapshot wiki.

6. Put it all together

app/Program.cs

using RocksDbSharp;

var path = Path.Combine(Path.GetTempPath(), "rocksdb-quickstart");
if (Directory.Exists(path)) Directory.Delete(path, recursive: true);

var options = new DbOptions()
    .SetCreateIfMissing(true)
    .IncreaseParallelism(Environment.ProcessorCount);

using (var db = RocksDb.Open(options, path))
{
    using (var batch = new WriteBatch())
    {
        batch.Put("a", "1");
        batch.Put("b", "2");
        batch.Put("c", "3");
        db.Write(batch);
    }

    using (var it = db.NewIterator())
    {
        for (it.SeekToFirst(); it.Valid(); it.Next())
        {
            Console.WriteLine($"{it.StringKey()} -> {it.StringValue()}");
        }
    }
}

Output

a -> 1
b -> 2
c -> 3

Where next?

Core Concepts

Open / read-only / secondary / TTL databases, options, and how the API layers fit together.

Guides

Iterators, write batches, snapshots, column families, merge operators, checkpoints, bulk loading.

Configuration

Tune DbOptions, ColumnFamilyOptions, ReadOptions, WriteOptions, and block-based tables.

Advanced

TTL, read-only / secondary instances, compaction, WAL inspection, replication, and native interop.

Referenced by

installation