Overview

rocksdb wraps librocksdb — a storage engine originally forked from Google's LevelDB and heavily optimized at Meta for flash storage, high write throughput, and production-scale workloads. It is used internally at Meta, LinkedIn, Microsoft, and many others.

The underlying engine uses a Log-Structured Merge-tree (LSM): writes go to an in-memory buffer (memtable) and a Write-Ahead Log, then are flushed and compacted into sorted SST files in the background. This design makes sequential writes very fast while keeping read performance competitive via bloom filters and block caches.

How RocksDB Compares

Store	Best for	Write throughput	Notes
RocksDB	Write-heavy workloads, large datasets, SSDs	Very high (LSM)	Background compaction; tunable compression per column family
LMDB	Read-heavy workloads, small datasets	Moderate (B-tree)	Memory-mapped, MVCC, simpler API; writes serialized through one writer
SQLite	Relational data, SQL queries	Low–moderate	Key-value only in RocksDB; RocksDB is much faster for raw KV throughput
LevelDB	Same niche as RocksDB	Good	RocksDB is the actively maintained fork with many more features (column families, compression, statistics, tuning options)

Quick Start

Open, write, read, close

uses rocksdb;

{ Open (creates the database if it doesn't exist) }
var db := Open('/data/mydb');

Put(db, 'hello', 'world');
Put(db, 'counter', '42');

var v := Get(db, 'hello');
WriteLn('hello = ' + v);           { hello = world }

WriteLn(Exists(db, 'missing'));  { False }

Delete(db, 'counter');
Close(db);

Open with custom options

uses rocksdb;

var opts: TRocksOptions;
opts.CreateIfMissing      := True;
opts.WriteBufferSize      := 128 * 1024 * 1024;  { 128 MB memtable }
opts.MaxWriteBufferNumber := 4;
opts.Compression          := rcZstd;
opts.BloomBitsPerKey      := 10;
opts.BlockCacheSize       := 256 * 1024 * 1024;  { 256 MB block cache }
opts.Parallelism          := 4;

var db := OpenEx('/data/mydb', opts);
{ ... use db ... }
Close(db);

Open / Close API

Function	Description
Open(Path)	Open database at Path, creating it if missing. Returns a TRocksDB handle.
OpenEx(Path, Opts)	Open with a TRocksOptions record for full control over buffer sizes, compression, bloom filters, and parallelism.
OpenReadOnly(Path)	Open an existing database in read-only mode. Writes will fail. Useful for inspection or backup readers.
Close(DB)	Flush pending writes and close the database. Always call this before the program exits.
Destroy(Path)	Delete the database and all its files at Path. Irreversible.

Basic Read / Write API

Function	Description
Put(DB, Key, Value)	Write a key-value pair. Overwrites any existing value for Key.
Get(DB, Key)	Read a value by key. Returns empty string '' if the key does not exist.
Exists(DB, Key)	Check whether a key exists. Uses the bloom filter for fast negative lookups.
Delete(DB, Key)	Delete a key. The entry is not immediately removed from disk; compaction reclaims the space.
MultiGet(DB, Keys)	Batch-read multiple keys in a single call. More efficient than N individual Get calls.

Write Batch API

A write batch groups multiple put/delete operations into a single atomic commit. Either all changes are applied or none. Batches are also faster than individual writes because they amortize the WAL flush cost.

Function	Description
NewBatch	Allocate a new empty write batch. Returns a TRocksBatch handle.
FreeBatch(B)	Release the batch handle when it is no longer needed.
BatchPut(B, Key, Value)	Stage a put operation in the batch.
BatchDelete(B, Key)	Stage a delete operation in the batch.
WriteBatch(DB, B)	Commit the batch atomically to the database.
ClearBatch(B)	Reset the batch to empty so it can be reused without re-allocating.
BatchCount(B)	Returns the number of operations currently staged in the batch.

uses rocksdb;

var db := Open('/data/events');
var b  := NewBatch;

for var i := 0 to Length(events) - 1 do
  BatchPut(b, 'evt:' + IntToStr(i), events[i]);

WriteLn('Staged: ' + IntToStr(BatchCount(b)) + ' ops');
WriteBatch(db, b);   { atomic commit }
FreeBatch(b);
Close(db);

Iterator API

Iterators provide a sorted scan over all keys in the database (or a column family). They capture a snapshot of the state at creation time, so concurrent writes do not affect the iteration.

Function	Description
NewIterator(DB)	Create an iterator over the default column family. Returns a TRocksIter handle.
FreeIterator(It)	Release the iterator handle.
IterSeekFirst(It)	Position the iterator at the first (smallest) key.
IterSeekLast(It)	Position the iterator at the last (largest) key.
IterSeek(It, Target)	Seek to the first key that is >= Target. Use for range scans.
IterNext(It)	Advance to the next key in ascending order.
IterPrev(It)	Move to the previous key in descending order.
IterValid(It)	Returns True if the iterator is positioned at a valid entry.
IterKey(It)	Returns the key at the current iterator position.
IterValue(It)	Returns the value at the current iterator position.

uses rocksdb;

var db := Open('/data/mydb');
var it := NewIterator(db);

{ Scan all keys with prefix 'user:' }
IterSeek(it, 'user:');
while IterValid(it) do
begin
  var k := IterKey(it);
  if Copy(k, 1, 5) <> 'user:' then Break;
  WriteLn(k + ' = ' + IterValue(it));
  IterNext(it);
end;

FreeIterator(it);
Close(db);

Snapshot API

Snapshots give you a consistent, point-in-time read view of the database. Reads through a snapshot see exactly the state of the database at the moment the snapshot was created, regardless of subsequent writes.

Function	Description
NewSnapshot(DB)	Create a consistent read snapshot. Returns a TRocksSnap handle. Compaction will not remove data that the snapshot still references.
FreeSnapshot(DB, Snap)	Release the snapshot. Compaction is free to reclaim data that is no longer referenced.
GetSnap(DB, Snap, Key)	Read a key as of the snapshot point in time. Returns the value that existed when the snapshot was taken.

uses rocksdb;

var db   := Open('/data/mydb');
Put(db, 'x', 'before');

var snap := NewSnapshot(db);

Put(db, 'x', 'after');   { write after snapshot }

WriteLn(Get(db, 'x'));             { after }
WriteLn(GetSnap(db, snap, 'x'));   { before }

FreeSnapshot(db, snap);
Close(db);

Column Family API

Column families are separate key spaces within a single RocksDB instance — similar to tables in a relational database. Each column family has its own memtable, SST files, and compaction settings, but shares a single WAL with the database.

Function	Description
ListColumnFamilies(Path)	Return the names of all column families in the database at Path (without opening it).
CreateColumnFamily(DB, Name)	Create a new column family and return its TRocksCF handle.
GetColumnFamily(DB, Name)	Get the handle for an existing column family by name.
PutCF(DB, CF, Key, Value)	Write a key-value pair to a specific column family.
GetCF(DB, CF, Key)	Read a value from a specific column family.
DeleteCF(DB, CF, Key)	Delete a key from a specific column family.

uses rocksdb;

var db      := Open('/data/multi');
var cfUsers := CreateColumnFamily(db, 'users');
var cfPosts := CreateColumnFamily(db, 'posts');

PutCF(db, cfUsers, 'u:1001', '{"name":"Alice"}');
PutCF(db, cfPosts, 'p:5001', '{"title":"Hello"}');

WriteLn(GetCF(db, cfUsers, 'u:1001'));
Close(db);

Maintenance API

Routine maintenance operations for managing disk usage and diagnosing performance.

Function	Description
CompactRange(DB)	Trigger a manual compaction over all keys. Merges SST files, removes deleted entries, and frees disk space. Can be slow on large databases.
Flush(DB)	Flush the in-memory memtable to a new SST file immediately. Useful before taking a filesystem backup.
GetStats(DB)	Returns a TRocksStats record with counts and size metrics for the database.
GetProperty(DB, Property)	Read a named RocksDB internal property as a string. E.g. 'rocksdb.stats', 'rocksdb.num-files-at-level0', 'rocksdb.estimate-num-keys'.
RocksDBVersion	Returns the version string of the linked librocksdb (e.g. '8.3.2').

uses rocksdb;

var db := Open('/data/mydb');

var stats := GetStats(db);
WriteLn('Files:      ' + IntToStr(stats.NumFiles));
WriteLn('Keys:       ' + IntToStr(stats.NumKeys));
WriteLn('Data size:  ' + IntToStr(stats.TotalDataSize));
WriteLn('Cache used: ' + IntToStr(stats.BlockCacheUsage));

WriteLn(GetProperty(db, 'rocksdb.stats'));
WriteLn('Version: ' + RocksDBVersion);

Close(db);

Types Reference

Handle types

type
  TRocksDB    = Integer;  { database handle }
  TRocksCF    = Integer;  { column family handle }
  TRocksBatch = Integer;  { write batch handle }
  TRocksIter  = Integer;  { iterator handle }
  TRocksSnap  = Integer;  { snapshot handle }

TRocksCompression

type
  TRocksCompression = (
    rcNone   = 0,   { no compression }
    rcSnappy = 1,   { fast, moderate ratio }
    rcZlib   = 2,
    rcBZip2  = 3,
    rcLZ4    = 4,   { fastest decompression }
    rcLZ4HC  = 5,   { LZ4 high-compression mode }
    rcZstd   = 7    { best ratio, fast enough for most workloads }
  );

TRocksOptions

type
  TRocksOptions = record
    CreateIfMissing     : Boolean;  { create DB if it doesn't exist }
    ErrorIfExists       : Boolean;
    MaxOpenFiles        : Integer;  { -1 = unlimited }
    WriteBufferSize     : Int64;    { bytes, default 64 MB }
    MaxWriteBufferNumber: Integer;
    TargetFileSizeBase  : Int64;
    Compression         : TRocksCompression;
    BloomBitsPerKey     : Integer;  { 10 is a good default }
    BlockCacheSize      : Int64;    { bytes, default 8 MB }
    Parallelism         : Integer;  { 0 = auto }
  end;

TRocksReadOptions

type
  TRocksReadOptions = record
    Snapshot       : TRocksSnap;  { 0 = no snapshot }
    FillCache      : Boolean;
    VerifyChecksums: Boolean;
  end;

TRocksWriteOptions

type
  TRocksWriteOptions = record
    Sync      : Boolean;  { fsync on write — slower but durable }
    DisableWAL: Boolean;  { skip WAL — faster, not crash-safe }
  end;

TRocksStats

type
  TRocksStats = record
    NumFiles       : Int64;  { total SST files on disk }
    TotalDataSize  : Int64;  { bytes on disk }
    NumKeys        : Int64;  { estimated key count }
    MemTableSize   : Int64;  { current memtable usage }
    BlockCacheUsage: Int64;  { bytes used in block cache }
  end;

Key Concepts

LSM-tree write path

All writes go first to the Write-Ahead Log (WAL) for durability, then into the in-memory memtable. When the memtable reaches its size limit (WriteBufferSize), it is flushed to an immutable SST file. Background compaction threads periodically merge and sort SST files, removing deleted keys and applying compaction-level compression.

Bloom filters

Each SST file carries a bloom filter keyed by BloomBitsPerKey. Before reading an SST file, RocksDB probes the bloom filter; if the result is negative (key definitely absent) the file read is skipped entirely. This makes reads of non-existent keys very fast. A value of 10 bits per key gives roughly a 1% false-positive rate.

Column families

Use column families to logically separate different kinds of data within a single database process. This avoids opening multiple database instances while still giving each namespace its own memtable, compression settings, and compaction policy. The default column family ('default') is always present and is what Put/Get/Delete use.