Skip to main content

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 }