Skip to main content

Overview

Write stalls occur when RocksDB slows down or temporarily stops accepting writes to prevent running out of resources. This is a critical flow control mechanism that protects database stability.
Write stalls indicate that writes are arriving faster than compaction can process them. While stalls protect the database, they impact write throughput and latency.

Why Write Stalls Happen

From advanced_options.h:539-716, RocksDB triggers write stalls when:
  1. Too many L0 files - Exceeds level0_slowdown_writes_trigger or level0_stop_writes_trigger
  2. Pending compaction bytes - Exceeds soft_pending_compaction_bytes_limit or hard_pending_compaction_bytes_limit
  3. Too many memtables - Immutable memtables waiting for flush

Stall Conditions

Level 0 File Thresholds

From advanced_options.h:539-553:
How it works:
Dynamically changeable through SetOptions() API.

Pending Compaction Bytes

From advanced_options.h:702-716:
Purpose: Prevents unbounded accumulation of data awaiting compaction.

Memtable Limits

From advanced_options.h:259-270:
Write stalls when:
  • Active memtable is full
  • All max_write_buffer_number slots are occupied
  • Flush can’t keep up with write rate

Write Delay Rate

When slowdown is triggered, writes are delayed to this rate:
RocksDB may automatically adjust delayed_write_rate based on flush/compaction speed to find the optimal rate.

Monitoring Write Stalls

Statistics

From statistics.h:205:
Check if stalls are occurring:

Histogram

From statistics.h:622:

Database Properties

Preventing Write Stalls

1. Increase L0 Thresholds

Increasing thresholds allows more L0 files, which can slow down reads and require more compaction resources.

2. Increase Write Buffers

From advanced_options.h:259-282:
Larger buffers mean:
  • Fewer L0 files created
  • More time between flushes
  • Higher memory usage

3. Increase Compaction Resources

4. Adjust Compaction Limits

5. Optimize Compaction Speed

6. Enable Dynamic Level Bytes

From advanced_options.h:581-665:
Dynamic level bytes:
  • Adapts to write traffic
  • Reduces write amplification
  • More predictable LSM shape

Handling Stalls in Applications

Detect and Retry

Proactive Monitoring

Advanced Configuration

Rate Limiter

Control flush/compaction I/O to leave headroom for user requests:

Disable Auto Compaction (Advanced)

Disabling auto compaction is dangerous. Only use if you have a sophisticated manual compaction strategy.

Troubleshooting Common Scenarios

Scenario 1: Sudden Write Spike

Symptoms: Writes stall during high-traffic periods Solutions:

Scenario 2: Slow Compaction

Symptoms: Persistent stalls even with moderate write rate Solutions:

Scenario 3: Small Writes, Many L0 Files

Symptoms: Frequent small flushes creating many L0 files Solutions:

Best Practices

Prevention is better than cure: Configure RocksDB to handle your expected peak write rate with headroom.
  1. Monitor proactively: Alert when approaching stall conditions (80% of threshold)
  2. Size write buffers appropriately: Balance memory usage and flush frequency
  3. Provision compaction resources: Ensure max_background_jobs can handle write rate
  4. Use dynamic level bytes: Enables better adaptation to write patterns
  5. Test under load: Validate configuration with realistic write workloads
  6. Plan for bursts: Size buffers to absorb temporary write spikes

See Also