tuwunel_core/config/database.rs
1//! Configures online database backups and request workers.
2//!
3//! Backup settings select storage and retention for RocksDB snapshots. Pool
4//! settings control worker affinity, concurrency, and request queue capacity.
5
6use std::path::PathBuf;
7
8use serde::Deserialize;
9use tuwunel_macros::config_example_generator;
10
11use super::true_fn;
12use crate::utils::sys::available_parallelism;
13
14/// Database backups and worker pool
15///
16/// Holds two sub-sections: `[global.database.backup]` for online backups,
17/// which stay unavailable until `database.backup.path` is set, and
18/// `[global.database.pool]` for the threads that serve database requests,
19/// sized from the hardware at startup. The database location is
20/// `database_path` under `[global]`; engine tuning is in `[global.rocksdb]`.
21#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
22#[derive(Clone, Debug, Default, Deserialize)]
23#[config_example_generator(
24 filename = "tuwunel-example.toml",
25 section = "global.database",
26 group = "true",
27 ignore = "backup pool"
28)]
29pub struct Database {
30 /// Settings for database backup.
31 ///
32 /// display: section
33 #[serde(default)]
34 pub backup: Backup,
35
36 /// Settings for database pool.
37 ///
38 /// display: section
39 #[serde(default)]
40 pub pool: Pool,
41}
42
43/// Online database backups
44///
45/// Copies the RocksDB database into a backup repository while the server
46/// keeps running. Backups are unavailable until `path` names a directory
47/// the server can write to, and even then run only on request, with
48/// `!admin server backup-database`. Both keys apply on reload.
49///
50/// Tips:
51/// - `keep` defaults to 1, so each backup replaces the previous one; raise
52/// it to retain more.
53/// - Backups hold the database only. Media stored under `database_path` or
54/// in storage providers needs its own copy.
55/// - For scheduled backups, add `"server backup-database"` to
56/// `admin.signal_execute` and send the server `SIGUSR2` from a timer.
57/// - To restore, stop the server and start it with `--restore-backup`; it
58/// replaces the database at `database_path` before opening it. See
59/// <https://tuwunel.chat/backups.html>.
60#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
61#[derive(Clone, Debug, Deserialize)]
62#[config_example_generator(
63 filename = "tuwunel-example.toml",
64 section = "global.database.backup",
65 group = "true"
66)]
67pub struct Backup {
68 /// Selects a writable directory for online database backups.
69 ///
70 /// Backups use the RocksDB Backup engine API. See
71 /// https://tuwunel.chat/maintenance.html#backups for setup and
72 /// maintenance.
73 ///
74 /// reloadable: yes
75 /// example: "/opt/tuwunel-db-backups"
76 /// legacy: database_backup_path
77 pub path: Option<PathBuf>,
78
79 /// Sets how many online RocksDB backups to retain.
80 ///
81 /// When `database.backup.path` is configured, the oldest backups are
82 /// deleted to enforce this limit. The value must be at least 1;
83 /// `backup-database` returns an error at 0 or below.
84 ///
85 /// reloadable: yes
86 /// default: 1
87 /// legacy: database_backups_to_keep
88 #[serde(default = "default_keep")]
89 pub keep: i16,
90}
91
92/// Database worker pool
93///
94/// The threads that execute database reads and writes, and the queues that
95/// feed them. Sizes are derived when the database opens, from the CPU count
96/// and, where it can be detected, the queue layout of the storage device
97/// under `database_path`. Changes need a restart.
98///
99/// Tips:
100/// - Under a cgroup task (pids) limit, as in many containers, startup warns
101/// when the pool may exceed it; raise the limit or lower `max_workers`.
102/// - `[global.runtime.stream]` scales its concurrency from this pool.
103#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
104#[derive(Clone, Copy, Debug, Deserialize)]
105#[config_example_generator(
106 filename = "tuwunel-example.toml",
107 section = "global.database.pool",
108 group = "true"
109)]
110pub struct Pool {
111 /// Pins database pool workers to the CPU cores that share their storage
112 /// queue.
113 ///
114 /// It has no effect unless tuwunel was built with the `cpu_affinity`
115 /// feature.
116 ///
117 /// default: true
118 /// legacy: db_pool_affinity
119 #[serde(default = "true_fn")]
120 pub affinity: bool,
121
122 /// Sets the number of database frontend pool worker threads.
123 ///
124 /// Match the system I/O capabilities, such as queue depth or
125 /// simultaneous requests in flight. The default is four times the
126 /// available CPU thread count, clamped from 32 through 1024. This
127 /// setting applies only when `database.pool.affinity` is disabled or
128 /// unavailable; otherwise the worker count is determined automatically.
129 ///
130 /// default: varies by system
131 /// legacy: db_pool_workers
132 #[serde(default = "default_workers")]
133 pub workers: usize,
134
135 /// Limits each automatically detected database worker group.
136 ///
137 /// When `database.pool.affinity` is enabled and available, this value is
138 /// multiplied by the number of CPU cores sharing a device queue because
139 /// workers can run on any of those cores. The limit prevents performance
140 /// degradation when thread pooling cannot scale to the full capacity of
141 /// high-end hardware.
142 ///
143 /// default: 32
144 /// legacy: db_pool_workers_limit
145 #[serde(default = "default_workers_limit")]
146 pub workers_limit: usize,
147
148 /// Limits the total number of workers across all database worker groups.
149 ///
150 /// Worker counts are reduced when their sum exceeds this limit, but each
151 /// populated group retains at least one worker, making the populated
152 /// group count the effective floor. The default generally constrains
153 /// larger systems with 16 or more cores. Thread pooling cannot reach
154 /// full hardware capacity, but this limit can be raised on huge systems
155 /// when groups are too small and scheduling overhead is not the
156 /// bottleneck.
157 ///
158 /// default: 2048
159 /// legacy: db_pool_max_workers
160 #[serde(default = "default_max_workers")]
161 pub max_workers: usize,
162
163 /// Sets the capacity multiplier for database frontend pool request
164 /// queues.
165 ///
166 /// Each queue capacity is this value multiplied by the pool worker
167 /// count. Tokio tasks submitting requests yield when the queue is full,
168 /// providing flow control that avoids buffer bloat. A value that is too
169 /// low can inhibit throughput.
170 ///
171 /// default: 4
172 /// legacy: db_pool_queue_mult
173 #[serde(default = "default_queue_mult")]
174 pub queue_mult: usize,
175}
176
177impl Default for Backup {
178 fn default() -> Self { Self { path: None, keep: default_keep() } }
179}
180
181impl Default for Pool {
182 fn default() -> Self {
183 Self {
184 affinity: true_fn(),
185 workers: default_workers(),
186 workers_limit: default_workers_limit(),
187 max_workers: default_max_workers(),
188 queue_mult: default_queue_mult(),
189 }
190 }
191}
192
193fn default_keep() -> i16 { 1 }
194
195fn default_workers() -> usize {
196 available_parallelism()
197 .saturating_mul(4)
198 .clamp(32, 1024)
199}
200
201fn default_workers_limit() -> usize { 32 }
202
203fn default_max_workers() -> usize { 2048 }
204
205fn default_queue_mult() -> usize { 4 }