Overview
RocksDB provides two main option types:DBOptions for database-level settings and ColumnFamilyOptions for column family-level settings. The Options struct combines both.
DBOptions
Database-level options that affect the entire DB instance.File and Directory Options
create_if_missing
bool
default:"false"
Create the database directory if it doesn’t exist
create_missing_column_families
error_if_exists
db_paths
db_log_dir
This is NOT for WALs (Write-Ahead Logs).
wal_dir
Performance Options
max_open_files
int
default:"-1"
Number of open files that can be used by the DB. Value -1 means files opened are always kept open.
max_file_opening_threads
max_background_jobs
int
default:"2"
Maximum number of concurrent background jobs (compactions and flushes)
max_subcompactions
Write-Ahead Log Options
max_total_wal_size
uint64_t
default:"0"
Maximum total size of WAL files. When exceeded, forces flush of column families backed by oldest WAL. If 0, dynamically set to [sum of all write_buffer_size * max_write_buffer_number] * 4.
WAL_ttl_seconds
WAL_size_limit_MB
recycle_log_file_num
Validation and Checking
paranoid_checks
bool
default:"true"
Enable pro-active checks for DB or data corruption. When true, DB enters read-only mode on write failure.
track_and_verify_wals_in_manifest
verify_sst_unique_id_in_manifest
Environment and I/O
env
use_fsync
use_direct_reads
use_direct_io_for_flush_and_compaction
allow_mmap_reads
bool
default:"false"
Allow OS to mmap files for reading SST tables. Not recommended for 32-bit OS.
allow_mmap_writes
allow_fallocate
bool
default:"true"
Enable file preallocation for WAL, SST, and Manifest files.
Statistics and Monitoring
statistics
stats_dump_period_sec
unsigned int
default:"600"
If non-zero, dump rocksdb.stats to LOG every N seconds (default: 10 minutes)
stats_persist_period_sec
persist_stats_to_disk
Rate Limiting
rate_limiter
std::shared_ptr<RateLimiter>
default:"nullptr"
Limits internal file read/write bandwidth for flush and compaction operations.
sst_file_manager
- Throttle deletion rate
- Track total size of SST files
- Set maximum allowed space limit
- Can be shared between multiple DBs
Manifest Options
max_manifest_file_size
uint64_t
default:"1GB"
Manifest file is rolled over when reaching this limit AND the space amp limit. Used as minimum for auto-tuned max manifest size.
max_manifest_space_amp_pct
int
default:"500"
Controls auto-tuned balance of manifest write and space amplification. New manifest created when current size exceeds max(max_manifest_file_size, est_compacted_size * (1 + pct/100)).
- 0: Every write generates new manifest (testing only)
- 100: ~1.0 write amp, ~1.0 space amp
- 500: 0.2 write amp, ~5.0 space amp (recommended)
- 10000: 0.01 write amp, ~100 space amp
ColumnFamilyOptions
Column family-level options that can be set independently for each column family.Basic Options
comparator
const Comparator*
default:"BytewiseComparator()"
Defines the order of keys in the table. Must be the same as used in previous opens of the same DB.
merge_operator
Memtable Options
write_buffer_size
size_t
default:"64MB"
Amount of data to build up in memory before converting to sorted on-disk file. Larger values increase performance, especially during bulk loads.
max_write_buffer_number
min_write_buffer_number_to_merge
Compression
compression
CompressionType
default:"kSnappyCompression"
Compression algorithm for blocks. Default is kSnappyCompression if linked, otherwise kNoCompression.
- Compression: ~200-500MB/s
- Decompression: ~400-800MB/s
bottommost_compression
compression_per_level
compression setting.
Dynamically changeable through SetOptions() API.
Compaction Options
compaction_style
CompactionStyle
default:"kCompactionStyleLevel"
Compaction style: Level-based, Universal, FIFO, or None
compaction_pri
level0_file_num_compaction_trigger
int
default:"4"
Number of files to trigger level-0 compaction. Value less than 0 disables level-0 compaction by file count.
level0_slowdown_writes_trigger
level0_stop_writes_trigger
disable_auto_compactions
Level Size Options
max_bytes_for_level_base
uint64_t
default:"256MB"
Maximum total data size for level-1. Maximum for level L is calculated as max_bytes_for_level_base * (max_bytes_for_level_multiplier ^ (L-1)).
max_bytes_for_level_multiplier
level_compaction_dynamic_level_bytes
bool
default:"true"
Pick target size of each level dynamically. Provides more predictable LSM tree shape and better space amplification.
File Size Options
target_file_size_base
uint64_t
default:"64MB"
Target file size for compaction (level-1). Size for level L is target_file_size_base * (target_file_size_multiplier ^ (L-1)).
target_file_size_multiplier
Table Factory
table_factory
Prefix and Filtering
prefix_extractor
std::shared_ptr<const SliceTransform>
default:"nullptr"
Function to put keys in contiguous groups (prefixes) for Bloom filter optimization.
TTL and Compaction Timing
ttl
uint64_t
default:"30 days"
Time-to-live in seconds. Files with all keys older than TTL will be compacted. 0 means disabled, 0xfffffffffffffffe means use default (30 days for block-based table).
periodic_compaction_seconds
Options Struct
Combines DBOptions and ColumnFamilyOptions for convenience.Helper Methods
OptimizeForSmallDb
OptimizeForPointLookup
OptimizeLevelStyleCompaction
OptimizeUniversalStyleCompaction
IncreaseParallelism
int
default:"16"
Total number of background threads for flush and compaction. Good value is number of CPU cores.
You almost definitely want to call this if your system is bottlenecked by RocksDB.