Performance Tuning

writes/s ~ goroutines x (1000 / window_ms)

./veltrixdb --wal-flush-window-ms 5 --vlog-flush-window-ms 5

Widening the window trades write latency (one window's worth, at most) for higher sustained write throughput by amortizing fdatasync across more writers per batch.

Batch operations

Always prefer MultiPut/MultiGet over individual PUT/GET calls when operating on multiple keys — they share a single network round trip.

The TCP server automatically coalesces back-to-back PUTs from the same connection into a MultiPut, so batching benefits apply even without client-side changes.

Disk density and packing

Batched writes pack multiple records per 4 KB VLog block, which materially changes on-disk density at small value sizes:

Packing is automatic for MultiPut and pipelined PUTs. A single unbatched Put uses the unpacked lock-free path instead. You can verify actual packing efficiency with veltrixdb_vlog_file_bytes / veltrixdb_storage_writes_total ~ value_size + 24.

Cache tuning

-cache 65536      # 64 GB
--auto-tune       # VeltrixDB picks 85% of available RAM
--read-heavy      # 400 GB preset + scan-resistant tuning

-read-heavy is a preset documented in the server flags reference as a 400 GB cache with an extended GC interval — use it for workloads dominated by reads where you can afford more RAM and want to bias GC toward less frequent, larger passes.

Check cache effectiveness with veltrixdb_cache_hits_total / (hits + misses). Small values (≤256 B) resist eviction more aggressively under the LIRS policy, so workloads with many small values benefit the most from a larger cache.

Admission control

VeltrixDB throttles background GC based on an exponentially-weighted moving average (EWMA) of read latency, to keep GC from competing with foreground reads for NVMe bandwidth:

If veltrixdb_storage_write_admission_throttles_total is rising, read latency has crossed the 4 ms threshold and writes are being intentionally slowed to protect read latency. Diagnose the underlying cause with veltrixdb_storage_read_latency_seconds before changing any other knob — raising the cache size or flush window will not help if the disk itself is the bottleneck.

Common problems