tuwunel_core/config/rocksdb.rs
1//! Configures the RocksDB engine and its resource limits.
2//!
3//! Settings cover memory, compression, logging, and database recovery.
4
5use serde::Deserialize;
6use tuwunel_macros::config_example_generator;
7
8use super::{parallelism_scaled_f64, true_fn};
9use crate::utils::bytes::deserialize_bytesize_usize;
10
11/// RocksDB storage engine
12///
13/// Tunes the RocksDB engine behind the database at `database_path`. Every
14/// key is read when the database opens, so changes need a restart. The
15/// defaults assume SSD or NVMe storage, and most keys only trade memory,
16/// threads or log volume for speed or diagnostics.
17///
18/// The recovery keys are different: `recovery_mode` 2 or 3 and `repair`
19/// can discard data, so back up `database_path` first and revert them once
20/// the server starts cleanly.
21///
22/// Tips:
23/// - On btrfs or ZFS set `allow_fallocate = false`; startup warns while it
24/// is left on there. On ZFS also set `direct_io = false`.
25/// - `recovery_mode` accepts 0 to 3; a larger value panics at startup.
26/// - `cache.capacity_modifier` also scales `write_buffer_capacity_mb`.
27#[derive(Clone, Debug, Deserialize)]
28#[config_example_generator(
29 filename = "tuwunel-example.toml",
30 section = "global.rocksdb",
31 group = "true"
32)]
33pub struct Rocksdb {
34 /// Sets the memory available to database read caches as a float in megabytes.
35 ///
36 /// Increasing this may improve performance when memory is available; like
37 /// individual LRU caches, the default scales with CPU core count to 128.0 + (64.0
38 /// * CPU core count).
39 ///
40 /// default: varies by system
41 /// legacy: db_cache_capacity_mb
42 #[serde(default = "default_cache_capacity_mb")]
43 pub cache_capacity_mb: f64,
44
45 /// Sets the memory available to database write caches as a float in megabytes.
46 ///
47 /// Increasing this may improve performance when memory is available; like
48 /// individual LRU caches, the default scales with CPU core count to 48.0 + (4.0 *
49 /// CPU core count).
50 ///
51 /// default: varies by system
52 /// legacy: db_write_buffer_capacity_mb
53 #[serde(default = "default_write_buffer_capacity_mb")]
54 pub write_buffer_capacity_mb: f64,
55
56 /// Sets the log level for RocksDB LOG files in the database directory.
57 ///
58 /// This differs from the application log level; tuwunel still reports RocksDB
59 /// errors through tracing or panics on severe errors for safety.
60 ///
61 /// default: "error"
62 /// legacy: rocksdb_log_level
63 #[serde(default = "default_log_level")]
64 pub log_level: String,
65
66 /// Routes RocksDB log messages to standard error.
67 ///
68 /// `rocksdb.log_level` still filters the emitted records. When disabled,
69 /// RocksDB uses the application's callback logger instead.
70 /// legacy: rocksdb_log_stderr
71 #[serde(default)]
72 pub log_stderr: bool,
73
74 /// Sets the maximum RocksDB LOG file size before rotation.
75 ///
76 /// Accepts an integer byte count or a string with SI/IEC suffix such as "4 MiB".
77 ///
78 /// default: 4194304
79 /// legacy: rocksdb_max_log_file_size
80 #[serde(
81 default = "default_max_log_file_size",
82 deserialize_with = "deserialize_bytesize_usize"
83 )]
84 pub max_log_file_size: usize,
85
86 /// Time in seconds before RocksDB will forcibly rotate logs.
87 ///
88 /// default: 0
89 /// legacy: rocksdb_log_time_to_roll
90 #[serde(default = "default_log_time_to_roll")]
91 pub log_time_to_roll: usize,
92
93 /// Uses RocksDB tunings tailored to spinning disks (HDDs).
94 ///
95 /// Leave this disabled on NVMe or SSD storage. When enabled, RocksDB skips
96 /// compaction readahead and parallel file-open threads at startup. This does not
97 /// affect Direct IO; see `rocksdb.direct_io`.
98 ///
99 /// legacy: rocksdb_optimize_for_spinning_disks
100 #[serde(default)]
101 pub optimize_for_spinning_disks: bool,
102
103 /// Enables direct-io to increase database performance via unbuffered I/O.
104 ///
105 /// For more details about direct I/O and RockDB, see:
106 /// https://github.com/facebook/rocksdb/wiki/Direct-IO
107 ///
108 /// Set this option to false if the database resides on a filesystem which
109 /// does not support direct-io like FUSE, or any form of complex filesystem
110 /// setup such as possibly ZFS.
111 /// legacy: rocksdb_direct_io
112 #[serde(default = "true_fn")]
113 pub direct_io: bool,
114
115 /// Sets the number of RocksDB threads for cleanup, sync, flush, and compaction.
116 ///
117 /// The stored value 0 selects the available logical thread count, with a minimum
118 /// of two.
119 ///
120 /// default: 0
121 /// legacy: rocksdb_parallelism_threads
122 #[serde(default = "default_parallelism_threads")]
123 pub parallelism_threads: usize,
124
125 /// Sets the maximum number of RocksDB LOG files retained.
126 ///
127 /// This must be at least 1, never 0. The default is 3 because these logs are
128 /// mainly useful for troubleshooting or debugging RocksDB bugs.
129 ///
130 /// default: 3
131 /// legacy: rocksdb_max_log_files
132 #[serde(default = "default_max_log_files")]
133 pub max_log_files: usize,
134
135 /// Sets the RocksDB database compression algorithm.
136 ///
137 /// Available options are "zstd", "bz2", "lz4", or "none", which disables
138 /// compression. ZSTD balances speed, storage, IO amplification, and CPU usage;
139 /// LZ4 offers more performance and lower CPU usage with less compression and more
140 /// storage use. See https://github.com/facebook/rocksdb/wiki/Compression for
141 /// details.
142 ///
143 /// default: "zstd"
144 /// legacy: rocksdb_compression_algo
145 #[serde(default = "default_compression_algo")]
146 pub compression_algo: String,
147
148 /// Level of compression the specified compression algorithm for RocksDB to
149 /// use.
150 ///
151 /// Default is 32767, which is internally read by RocksDB as the default
152 /// magic number and translated to the library's default compression level
153 /// as they all differ. See their `kDefaultCompressionLevel`.
154 ///
155 /// Note when using the default value we may override it with a setting
156 /// tailored specifically tuwunel.
157 ///
158 /// default: 32767
159 /// legacy: rocksdb_compression_level
160 #[serde(default = "default_compression_level")]
161 pub compression_level: i32,
162
163 /// Sets the compression level for the bottommost RocksDB data.
164 ///
165 /// The default 32767 is RocksDB's `kDefaultCompressionLevel`, translated to the
166 /// selected library's default level; tuwunel may override it with a tailored
167 /// setting. Bottommost data is generally old and less frequently accessed, so
168 /// higher compression may be useful; research the chosen algorithm.
169 ///
170 /// default: 32767
171 /// legacy: rocksdb_bottommost_compression_level
172 #[serde(default = "default_bottommost_compression_level")]
173 pub bottommost_compression_level: i32,
174
175 /// Whether to enable RocksDB's "bottommost_compression".
176 ///
177 /// At the expense of more CPU usage, this will further compress the
178 /// database to reduce more storage. It is recommended to use ZSTD
179 /// compression with this for best compression results. This may be useful
180 /// if you're trying to reduce storage usage from the database.
181 ///
182 /// See https://github.com/facebook/rocksdb/wiki/Compression for more details.
183 /// legacy: rocksdb_bottommost_compression
184 #[serde(default = "true_fn")]
185 pub bottommost_compression: bool,
186
187 /// Sets the database recovery mode for RocksDB WAL corruption.
188 ///
189 /// When corruption prevents startup, use mode 2 (PointInTime) to recover to the
190 /// last good state, seconds or minutes before the crash. Clients may need
191 /// "clear-cache & reload" after this rollback. After recovery succeeds, reset the mode
192 /// to its default and restart. In some cases the corruption error persists for at
193 /// least 30 minutes of operation in PointInTime mode.
194 ///
195 /// Only as a last resort if PointInTime fails, try mode 3
196 /// (SkipAnyCorruptedRecord), which may leave the server inconsistent. Default
197 /// mode 1 (TolerateCorruptedTailRecords) drops only the last entry if corrupted
198 /// during shutdown, with an extraordinarily low risk of desynchronizing clients.
199 /// Mode 0 (AbsoluteConsistency) disables all silent rollback. See
200 /// https://github.com/facebook/rocksdb/wiki/WAL-Recovery-Modes for mode details
201 /// and https://tuwunel.chat/troubleshooting.html#database-corruption for recovery
202 /// guidance.
203 ///
204 /// default: 1
205 /// legacy: rocksdb_recovery_mode
206 #[serde(default = "default_recovery_mode")]
207 pub recovery_mode: u8,
208
209 /// Enables paranoid SST file checks.
210 ///
211 /// Additional safety checks may improve database consistency at a performance
212 /// cost; see the RocksDB documentation for details:
213 /// https://github.com/facebook/rocksdb/wiki/Online-Verification#columnfamilyoptionsparanoid_file_checks
214 ///
215 /// legacy: rocksdb_paranoid_file_checks
216 #[serde(default)]
217 pub paranoid_file_checks: bool,
218
219 /// Enables runtime checksum verification in RocksDB.
220 ///
221 /// Checksums are enabled by default and usually hardware accelerated with low
222 /// overhead. Older or slower platforms may gain performance by disabling them.
223 ///
224 /// default: true
225 /// legacy: rocksdb_checksums
226 #[serde(default = "true_fn")]
227 pub checksums: bool,
228
229 /// Enables RocksDB atomic flush mode.
230 ///
231 /// This option is not intended for users and may be removed or ignored in future
232 /// versions. It may improve database integrity at the cost of performance.
233 ///
234 /// legacy: rocksdb_atomic_flush
235 #[serde(default)]
236 pub atomic_flush: bool,
237
238 /// Enables database repair for RocksDB SST corruption.
239 ///
240 /// Use this when the server reports corruption while running or panics,
241 /// especially for errors containing SST after startup; if startup fails, try
242 /// recovery mode first. Back up the database directory before running repair.
243 /// Disable repair mode and restart the server after repair finishes. See
244 /// https://tuwunel.chat/troubleshooting.html#database-corruption for recovery
245 /// details.
246 ///
247 /// legacy: rocksdb_repair
248 #[serde(default)]
249 pub repair: bool,
250
251 /// Opens RocksDB in read-only mode.
252 ///
253 /// Writes are rejected and missing column families cannot be created. This
254 /// mode is disabled by default.
255 /// legacy: rocksdb_read_only
256 #[serde(default)]
257 pub read_only: bool,
258
259 /// Opens RocksDB as a secondary follower of a primary instance.
260 ///
261 /// Writes are rejected while the primary's latest WAL can be replayed into
262 /// this instance's view. Missing column families cannot be created.
263 /// legacy: rocksdb_secondary
264 #[serde(default)]
265 pub secondary: bool,
266
267 /// Enables idle CPU priority for the compaction thread.
268 ///
269 /// This is disabled by default to prevent compaction from falling too far behind
270 /// on busy systems.
271 ///
272 /// legacy: rocksdb_compaction_prio_idle
273 #[serde(default)]
274 pub compaction_prio_idle: bool,
275
276 /// Enables idle IO priority for the compaction thread.
277 ///
278 /// This is enabled by default and usually advisable to prevent unexpected server
279 /// lag.
280 ///
281 /// legacy: rocksdb_compaction_ioprio_idle
282 #[serde(default = "true_fn")]
283 pub compaction_ioprio_idle: bool,
284
285 /// Enables RocksDB compaction.
286 ///
287 /// You should never need to disable this; if troubleshooting or a bug appears to
288 /// require it, contact the tuwunel Matrix room with details. Disabling compaction
289 /// causes explosive database growth, gradually poor performance, excessive disk
290 /// reads and writes, and slower shutdowns and startups.
291 ///
292 /// legacy: rocksdb_compaction
293 #[serde(default = "true_fn")]
294 pub compaction: bool,
295
296 /// Sets the level of database statistics collection from 0 to 6.
297 ///
298 /// Some admin commands that display database statistics require this setting;
299 /// higher levels may affect performance. Level 0 disables statistics, level 1
300 /// disables them in release mode and is the default, levels 2 to 3 have no
301 /// performance impact, levels 3 to 5 may affect performance, and level 6 collects
302 /// all statistics.
303 ///
304 /// default: 1
305 /// legacy: rocksdb_stats_level
306 #[serde(default = "default_stats_level")]
307 pub stats_level: u8,
308
309 /// Ignores the list of dropped columns set by developers.
310 ///
311 /// This should be set to true when knowingly moving between versions in
312 /// ways which are not recommended or otherwise forbidden, or for
313 /// diagnostic and development purposes; requiring preservation across such
314 /// movements.
315 ///
316 /// The developer's list of dropped columns is meant to safely reduce space
317 /// by erasing data no longer in use. If this is set to true that storage
318 /// will not be reclaimed as intended.
319 ///
320 /// default: false
321 /// legacy: rocksdb_never_drop_columns
322 #[serde(default)]
323 pub never_drop_columns: bool,
324
325 /// Allows RocksDB to preallocate WAL logs.
326 ///
327 /// Normally, RocksDB allocates certain types of files by calling
328 /// fallocate, writing the file contents, then truncating the logs to the
329 /// proper size. This causes pathological disk space usage on btrfs due to
330 /// how it interacts with its Copy-on-Write implementation. On ZFS,
331 /// fallocate(2) for preallocation is unsupported and returns EOPNOTSUPP;
332 /// only `FALLOC_FL_PUNCH_HOLE` and `FALLOC_FL_ZERO_RANGE` are implemented.
333 ///
334 /// Set this to false if you run the server on btrfs or ZFS, and do not
335 /// touch it otherwise.
336 ///
337 /// default: true
338 /// legacy: rocksdb_allow_fallocate
339 #[serde(default = "true_fn")]
340 pub allow_fallocate: bool,
341}
342
343impl Default for Rocksdb {
344 fn default() -> Self {
345 Self {
346 cache_capacity_mb: default_cache_capacity_mb(),
347 write_buffer_capacity_mb: default_write_buffer_capacity_mb(),
348 log_level: default_log_level(),
349 log_stderr: Default::default(),
350 max_log_file_size: default_max_log_file_size(),
351 log_time_to_roll: default_log_time_to_roll(),
352 optimize_for_spinning_disks: Default::default(),
353 direct_io: true_fn(),
354 parallelism_threads: default_parallelism_threads(),
355 max_log_files: default_max_log_files(),
356 compression_algo: default_compression_algo(),
357 compression_level: default_compression_level(),
358 bottommost_compression_level: default_bottommost_compression_level(),
359 bottommost_compression: true_fn(),
360 recovery_mode: default_recovery_mode(),
361 paranoid_file_checks: Default::default(),
362 checksums: true_fn(),
363 atomic_flush: Default::default(),
364 repair: Default::default(),
365 read_only: Default::default(),
366 secondary: Default::default(),
367 compaction_prio_idle: Default::default(),
368 compaction_ioprio_idle: true_fn(),
369 compaction: true_fn(),
370 stats_level: default_stats_level(),
371 never_drop_columns: Default::default(),
372 allow_fallocate: true_fn(),
373 }
374 }
375}
376
377fn default_cache_capacity_mb() -> f64 { 128.0 + parallelism_scaled_f64(64.0) }
378
379fn default_write_buffer_capacity_mb() -> f64 { 48.0 + parallelism_scaled_f64(4.0) }
380
381fn default_log_level() -> String { "error".to_owned() }
382
383fn default_max_log_file_size() -> usize { 4 * 1024 * 1024 }
384
385fn default_log_time_to_roll() -> usize { 0 }
386
387fn default_parallelism_threads() -> usize { 0 }
388
389fn default_max_log_files() -> usize { 3 }
390
391fn default_compression_algo() -> String {
392 cfg!(feature = "zstd_compression")
393 .then_some("zstd")
394 .unwrap_or("none")
395 .to_owned()
396}
397
398/// Default RocksDB compression level is 32767, which is internally read by
399/// RocksDB as the default magic number and translated to the library's default
400/// compression level as they all differ.
401///
402/// See their `kDefaultCompressionLevel`.
403#[expect(clippy::doc_markdown)]
404fn default_compression_level() -> i32 { 32767 }
405
406/// Default RocksDB compression level is 32767, which is internally read by
407/// RocksDB as the default magic number and translated to the library's default
408/// compression level as they all differ.
409///
410/// See their `kDefaultCompressionLevel`.
411#[expect(clippy::doc_markdown)]
412fn default_bottommost_compression_level() -> i32 { 32767 }
413
414fn default_recovery_mode() -> u8 { 1 }
415
416fn default_stats_level() -> u8 { 1 }