db_bench

Overview

db_bench is RocksDB’s primary benchmarking tool for measuring database performance across various workloads. It provides extensive configuration options and supports dozens of benchmark types including sequential writes, random reads, compaction testing, and mixed workloads. The tool is essential for:

Performance testing and regression detection
Tuning database configurations
Evaluating hardware capabilities
Comparing different compression algorithms
Stress testing concurrent operations

Building db_bench

Build a release binary for accurate performance measurements:

make clean
DEBUG_LEVEL=0 make db_bench

Always use release builds (DEBUG_LEVEL=0) for benchmarking. Debug builds include assertions and logging that significantly impact performance.

For debugging crashes during benchmarks:

make clean
make dbg

Basic Usage

Simple Sequential Write Benchmark

./db_bench --benchmarks=fillseq --db=/tmp/testdb

This performs a sequential write test with default settings (1 million keys, 16-byte keys, 100-byte values).

Random Read Benchmark

./db_bench --benchmarks=fillrandom,readrandom \
  --db=/tmp/testdb \
  --num=10000000 \
  --threads=16 \
  --cache_size=8388608000

Available Benchmarks

db_bench supports a comprehensive set of benchmark operations. Specify multiple benchmarks as a comma-separated list in execution order.

Write Benchmarks

fillseq

Write N values in sequential key order (async mode)

./db_bench --benchmarks=fillseq --num=1000000

fillrandom

Write N values in random key order (async mode)

./db_bench --benchmarks=fillrandom --num=1000000

fillsync

Write N/1000 values in random key order with sync mode

./db_bench --benchmarks=fillsync --num=1000000

overwrite

Overwrite N values in random key order (async mode)

./db_bench --benchmarks=fillrandom,overwrite --num=1000000

Read Benchmarks

readseq

Read N times sequentially

./db_bench --benchmarks=fillseq,readseq --num=1000000

readrandom

Read N times in random order

./db_bench --benchmarks=fillrandom,readrandom \
  --num=1000000 \
  --reads=10000000

readreverse

Read N times in reverse order

./db_bench --benchmarks=fillseq,readreverse --num=1000000

multireadrandom

Multi-key random reads using MultiGet API

./db_bench --benchmarks=fillrandom,multireadrandom \
  --num=1000000 \
  --batch_size=10 \
  --threads=16

Iterator Benchmarks

seekrandom - N random seeks, calling Next() seek_nexts times per seek
seekrandomwhilewriting - seekrandom with 1 thread doing overwrites
newiterator - Repeated iterator creation

./db_bench --benchmarks=fillrandom,seekrandom \
  --num=1000000 \
  --seek_nexts=10

Compaction Benchmarks

compact - Compact the entire DB
compactall - Compact the entire DB
compact0 - Compact L0 into L1
compact1 - Compact L1 into L2
waitforcompaction - Pause until compaction is complete

./db_bench --benchmarks=fillrandom,compact --num=10000000

Mixed Workload Benchmarks

readwhilewriting - 1 writer, N threads doing random reads
readrandomwriterandom - N threads doing random read-write
updaterandom - N threads doing read-modify-write for random keys

./db_bench --benchmarks=readwhilewriting \
  --num=10000000 \
  --threads=32 \
  --duration=300

Key Configuration Options

Database Size and Keys

Flag	Default	Description
`--num`	1000000	Number of key/values to place in database
`--key_size`	16	Size of each key in bytes
`--value_size`	100	Size of each value in bytes
`--compression_ratio`	0.5	Compression ratio for generated values

./db_bench --benchmarks=fillrandom \
  --num=100000000 \
  --key_size=20 \
  --value_size=400

Threading and Duration

Flag	Default	Description
`--threads`	1	Number of concurrent threads
`--duration`	0	Time in seconds for random-ops tests (0 = use —num)
`--batch_size`	1	Batch size for operations

./db_bench --benchmarks=readrandom \
  --threads=64 \
  --duration=600 \
  --num=100000000

Memory Configuration

Flag	Default	Description
`--cache_size`	32MB	Block cache size
`--write_buffer_size`	64MB	Size of write buffer (memtable)
`--max_write_buffer_number`	2	Number of write buffers
`--db_write_buffer_size`	0	Total size of all memtables

./db_bench --benchmarks=fillrandom,readrandom \
  --cache_size=17179869184 \  # 16GB
  --write_buffer_size=134217728 \  # 128MB
  --max_write_buffer_number=4

Compaction Settings

Flag	Default	Description
`--max_background_jobs`	2	Max background compaction/flush jobs
`--compaction_style`	0	0=Level, 1=Universal, 2=FIFO
`--subcompactions`	1	Number of subcompactions per job

./db_bench --benchmarks=fillrandom \
  --max_background_jobs=16 \
  --subcompactions=4 \
  --compaction_style=0

Compression

Flag	Description
`--compression_type`	Compression algorithm (snappy, zstd, lz4, etc.)
`--compression_level`	Compression level for algorithms that support it

./db_bench --benchmarks=fillrandom \
  --compression_type=zstd \
  --compression_level=3

Advanced Use Cases

Multi-Database Benchmarking

Test across multiple database instances:

./db_bench --benchmarks=fillrandom,readrandom \
  --num_multi_db=4 \
  --db=/tmp/testdb

Column Family Testing

./db_bench --benchmarks=fillrandom \
  --num_column_families=10 \
  --num_hot_column_families=3

Skewed Access Patterns

Use exponential distribution for read keys:

./db_bench --benchmarks=fillrandom,readrandom \
  --read_random_exp_range=2.0 \
  --num=10000000

Transaction Testing

./db_bench --benchmarks=randomtransaction \
  --num=1000000 \
  --transaction_db=true

Backup and Restore

./db_bench --benchmarks=fillrandom,backup,restore \
  --backup_rate_limit=104857600 \  # 100MB/s
  --restore_rate_limit=104857600

Output Interpretation

db_bench outputs performance metrics including:

ops/sec - Operations per second (throughput)
MB/s - Megabytes per second processed
micros/op - Microseconds per operation (latency)
Percentiles - P50, P75, P99, P99.9, P99.99 latencies

Use --histogram=true to get detailed latency distribution histograms.

Example output:

fillrandom   :       3.162 micros/op 316227 ops/sec;
  30.2 MB/s (1000000 ops)
readrandom   :       1.234 micros/op 810373 ops/sec;
  77.4 MB/s (10000000 of 10000000 found)

Statistics and Monitoring

Enable detailed statistics:

./db_bench --benchmarks=fillrandom,stats,readrandom,stats \
  --statistics=true \
  --histogram=true

Available meta operations:

stats - Print database statistics
resetstats - Reset database statistics
levelstats - Print number of files and bytes per level
sstables - Print SST file information

Performance Tips

Use appropriate cache size

Set --cache_size to approximately the size of your working set for read-heavy workloads.

Tune write buffer size

Larger write buffers reduce write amplification but use more memory. Balance based on your RAM availability.

Enable NUMA awareness

For multi-socket systems:

./db_bench --benchmarks=fillrandom \
  --enable_numa=true

Adjust thread count

Match --threads to your CPU core count for CPU-bound workloads.

Troubleshooting

Out of Memory

Reduce memory footprint:

./db_bench --benchmarks=fillrandom \
  --cache_size=1073741824 \  # 1GB
  --write_buffer_size=67108864 \  # 64MB
  --max_write_buffer_number=2

Slow Compaction

Increase compaction parallelism:

./db_bench --benchmarks=fillrandom \
  --max_background_jobs=8 \
  --subcompactions=4

High Write Amplification

Adjust compaction settings:

./db_bench --benchmarks=fillrandom \
  --level0_file_num_compaction_trigger=4 \
  --max_bytes_for_level_base=268435456

Source Reference

The db_bench tool is implemented in:

tools/db_bench_tool.cc - Main implementation with all benchmark logic
Build with: make db_bench (debug) or DEBUG_LEVEL=0 make db_bench (release)

For a complete list of all available flags and options, run ./db_bench --help or examine the DEFINE_* statements in tools/db_bench_tool.cc:111-708.

Get Started

Core Concepts

Developer Guide

Advanced Topics

Language Bindings

Tools & Utilities

Overview

Building db_bench

Basic Usage

Simple Sequential Write Benchmark

Random Read Benchmark

Available Benchmarks

Write Benchmarks

Read Benchmarks

Iterator Benchmarks

Compaction Benchmarks

Mixed Workload Benchmarks

Key Configuration Options

Database Size and Keys

Threading and Duration

Memory Configuration

Compaction Settings

Compression

Advanced Use Cases

Multi-Database Benchmarking

Column Family Testing

Skewed Access Patterns

Transaction Testing

Backup and Restore

Output Interpretation

Statistics and Monitoring

Performance Tips

Troubleshooting

Out of Memory

Slow Compaction

High Write Amplification

Source Reference

​Overview

​Building db_bench

​Basic Usage

​Simple Sequential Write Benchmark

​Random Read Benchmark

​Available Benchmarks

​Write Benchmarks

​Read Benchmarks

​Iterator Benchmarks

​Compaction Benchmarks

​Mixed Workload Benchmarks

​Key Configuration Options

​Database Size and Keys

​Threading and Duration

​Memory Configuration

​Compaction Settings

​Compression

​Advanced Use Cases

​Multi-Database Benchmarking

​Column Family Testing

​Skewed Access Patterns

​Transaction Testing

​Backup and Restore

​Output Interpretation

​Statistics and Monitoring

​Performance Tips

​Troubleshooting

​Out of Memory

​Slow Compaction

​High Write Amplification

​Source Reference

Overview

Building db_bench

Basic Usage

Simple Sequential Write Benchmark

Random Read Benchmark

Available Benchmarks

Write Benchmarks

Read Benchmarks

Iterator Benchmarks

Compaction Benchmarks

Mixed Workload Benchmarks

Key Configuration Options

Database Size and Keys

Threading and Duration

Memory Configuration

Compaction Settings

Compression

Advanced Use Cases

Multi-Database Benchmarking

Column Family Testing

Skewed Access Patterns

Transaction Testing

Backup and Restore

Output Interpretation

Statistics and Monitoring

Performance Tips

Troubleshooting

Out of Memory

Slow Compaction

High Write Amplification

Source Reference