grocksdb

You can customize how grocksdb links to libraries using Go build tags. This is useful if you want to override the default flags (-lrocksdb -pthread -lstdc++ -ldl -lm -lzstd -llz4 -lz -lsnappy) or use a cleaner set of links.

Use clean links

Use -tags grocksdb_clean_link to reduce the base flags to -lrocksdb -pthread -lstdc++ -ldl. This allows you to manually specify only the additional libraries you need.

Ignore library build flags

Use -tags grocksdb_no_link to ignore the library's internal build flags entirely and build strictly based on the flags you provide in CGO_LDFLAGS.

# Build with a cleaner set of flags
CGO_LDFLAGS="-L/path/to/rocksdb -lzstd" go build -tags grocksdb_clean_link

# Build ignoring library flags and using fully custom flags
CGO_LDFLAGS="-L/path/to/rocksdb -lrocksdb -lstdc++ -lzstd -llz4" go build -tags grocksdb_no_link

To build your Go application with grocksdb, you must provide the correct include and library paths via CGO_CFLAGS and CGO_LDFLAGS.

If your prerequisites are already in your system's linker paths, you can simply run:

go build

Otherwise, use the following patterns depending on your RocksDB installation and compression libraries.

# Standard build
CGO_CFLAGS="-I/path/to/rocksdb/include" \
CGO_LDFLAGS="-L/path/to/rocksdb -lrocksdb -lstdc++ -lm -lz -lsnappy -llz4 -lzstd" \
  go build

# Build with bz2 support
CGO_LDFLAGS="-L/path/to/rocksdb -lrocksdb -lstdc++ -lm -lz -lsnappy -llz4 -lzstd -lbz2" \
  go build

Before building grocksdb, you must install the following C libraries on your system:

• librocksdb (Required)
• libsnappy (Required)
• libz (Required)
• liblz4 (Required)
• libzstd (Required)
• libbz2 (Optional)

Refer to the official RocksDB installation guide to build these libraries.

The ReadTier type allows you to specify which cache levels a read request should process. If the required data is not found at the specified tier, the operation returns Status::Incomplete.

Available tiers:

• ReadAllTier (0): Reads data from memtable, block cache, OS cache, or storage. (Default)
• BlockCacheTier (1): Reads data from memtable or block cache only.
• PersistedTier (2): Reads data from memtable or block cache persisted data. Note: If WAL is disabled, this skips memtable data. Currently supports Get and MultiGet only (not iterators).
• MemtableTier (3): Reads data from memtable only. Used for memtable-only iterators.

opts := grocksdb.NewDefaultReadOptions()
opts.SetReadTier(grocksdb.BlockCacheTier)

The EncodingType defines how keys are written to the database.

• EncodingTypePlain: Always writes full keys without any special encoding.
• EncodingTypePrefix: Finds opportunities to write the same prefix once for multiple rows. Instead of the full key, it writes the size of the shared prefix and the remaining bytes.

Note for EncodingTypePrefix: You must use the same prefix extractor when reopening the file. The name of the prefix extractor is stored in the file and is bitwise compared upon reopening; a mismatch will return an error.

// Available types:
// grocksdb.EncodingTypePlain
// grocksdb.EncodingTypePrefix

The GetUpdatesSince method allows you to obtain an iterator positioned at a specific sequence number, effectively allowing you to read updates that occurred after a certain point.

Important Requirements:

• You must set WAL_ttl_seconds or WAL_size_limit_MB to large values. If the WAL files are cleared aggressively by RocksDB, the iterator may become invalid before you can read the updates.
• This API is not yet consistent with WritePrepared transactions.

Method:

• GetUpdatesSince(seqNumber uint64) (*WalIterator, error): Returns a WalIterator positioned at the first available sequence number after the requested one.

WriteBatchWI (Write Batch with Index) is a specialized batching type that allows for 'read-your-own-write' semantics. It maintains an index of Put, Merge, and Delete operations, enabling you to query the batch or use iterators to see pending changes before they are committed to the database.

Key features include:

• Index Support: Tracks updates to allow querying the batch directly.
• Iterators: Supports creating iterators that view the batch as a delta over a base iterator.
• Save Points: Allows rolling back the batch to a specific state using SetSavePoint and RollbackToSavePoint.

// Example initialization
wb := grocksdb.NewWriteBatchWI(1024, true)
defer wb.Destroy()

wb.Put([]byte("key"), []byte("value"))

// Read the value from the batch before committing to DB
val, err := wb.Get(opts, []byte("key"))

The COWList is designed for scenarios like CGO callback registries where reads are frequent and writes are occasional.

Concurrency Model:

• Reads: Non-blocking. Multiple goroutines can call Get simultaneously without contention.
• Writes: Only one write can occur at a time (enforced by sync.Mutex).
• Read/Write Interaction: Writes do not block reads, and reads do not block writes. A reader will always see a consistent, immutable snapshot of the list from the moment the read operation began.