RocksDB-backed CDC event log for the Rhei HTAP engine.

This crate provides [RocksDbCdcLog], a durable, high-throughput alternative to the trigger-based SQLite CDC log used in standard HTAP mode. Benchmarks show 5–7× higher write throughput compared to SQLite triggers, because RocksDB's LSM-tree write path has lower per-write overhead than SQLite's WAL trigger execution.

When to use this crate

This crate is compiled only when the parent workspace enables the rocksdb-cdc feature. The RocksDB C++ library is bundled via rust-rocksdb so no external installation is required.

Storage layout and key encoding

All data lives in RocksDB's default column family (no custom CFs). Two key namespaces co-exist:

Big-endian encoding is chosen so that RocksDB's default byte-wise comparator iterates events in sequence order without a custom comparator. Metadata keys start with 0xFF, which sorts after all valid sequence keys (which are non-negative i64 values encoded big-endian and therefore never start with 0xFF), so a forward iterator stops naturally before reaching metadata.

Durability and crash recovery

Every write goes through a WriteBatch, which RocksDB commits atomically. On crash recovery, [RocksDbCdcLog::open] reads the persisted META_LATEST_SEQ key to restore the in-memory sequence counter, so appends resume from the correct position without scanning all events.

The bridge watermark ([RocksDbCdcLog::append_and_set_bridge_watermark]) is written in the same WriteBatch as the events it covers, making the bridge operation idempotent: after a mid-write crash, either both the events and the watermark are present, or neither is.

Quick start

use rhei_cdc_rocksdb::{RocksDbCdcLog, RocksDbCdcConfig};

let config = RocksDbCdcConfig {
    path: "/var/lib/rhei/cdc_rocksdb".to_string(),
    create_if_missing: true,
};
let log = RocksDbCdcLog::open(&config).unwrap();