Skip to main content

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 }