rocket_db_pools/config.rs
1use rocket::serde::{Deserialize, Serialize};
2
3/// Base configuration for all database drivers.
4///
5/// A dictionary matching this structure is extracted from the active
6/// [`Figment`](crate::figment::Figment), scoped to `databases.name`, where
7/// `name` is the name of the database, by the
8/// [`Initializer`](crate::Initializer) fairing on ignition and used to
9/// configure the relevant database and database pool.
10///
11/// With the default provider, these parameters are typically configured in a
12/// `Rocket.toml` file:
13///
14/// ```toml
15/// [default.databases.db_name]
16/// url = "/path/to/db.sqlite"
17///
18/// # Only `url` is required. These have sane defaults and are optional.
19/// min_connections = 64
20/// max_connections = 1024
21/// connect_timeout = 5
22/// idle_timeout = 120
23/// ```
24///
25/// Alternatively, a custom provider can be used. For example, a custom `Figment`
26/// with a global `databases.name` configuration:
27///
28/// ```rust
29/// # use rocket::launch;
30/// #[launch]
31/// fn rocket() -> _ {
32/// let figment = rocket::Config::figment()
33/// .merge(("databases.name", rocket_db_pools::Config {
34/// url: "db:specific@config&url".into(),
35/// min_connections: None,
36/// max_connections: 1024,
37/// connect_timeout: 3,
38/// idle_timeout: None,
39/// }));
40///
41/// rocket::custom(figment)
42/// }
43/// ```
44///
45/// For general information on configuration in Rocket, see [`rocket::config`].
46/// For higher-level details on configuring a database, see the [crate-level
47/// docs](crate#configuration).
48// NOTE: Defaults provided by the figment created in the `Initializer` fairing.
49#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
50#[serde(crate = "rocket::serde")]
51pub struct Config {
52 /// Database-specific connection and configuration URL.
53 ///
54 /// The format of the URL is database specific; consult your database's
55 /// documentation.
56 pub url: String,
57 /// Minimum number of connections to maintain in the pool.
58 ///
59 /// **Note:** `deadpool` drivers do not support and thus ignore this value.
60 ///
61 /// _Default:_ `None`.
62 pub min_connections: Option<u32>,
63 /// Maximum number of connections to maintain in the pool.
64 ///
65 /// _Default:_ `workers * 4`.
66 pub max_connections: usize,
67 /// Number of seconds to wait for a connection before timing out.
68 ///
69 /// If the timeout elapses before a connection can be made or retrieved from
70 /// a pool, an error is returned.
71 ///
72 /// _Default:_ `5`.
73 pub connect_timeout: u64,
74 /// Maximum number of seconds to keep a connection idle or to recycle it.
75 ///
76 /// For SQLx and MongoDB, an idle connection is closed after this timeout
77 /// elapses. For Deadpool and Diesel, this limits the time allowed to
78 /// recycle a connection before reuse, including any health check; idle
79 /// connections are not closed. `None` disables the corresponding timeout.
80 ///
81 /// _Default:_ `None`.
82 pub idle_timeout: Option<u64>,
83}
84
85impl Default for Config {
86 fn default() -> Self {
87 Self {
88 url: Default::default(),
89 min_connections: Default::default(),
90 max_connections: rocket::Config::default().workers * 4,
91 connect_timeout: 5,
92 idle_timeout: Default::default(),
93 }
94 }
95}
96
97#[cfg(test)]
98mod tests {
99 use super::Config;
100
101 #[test]
102 fn default_values_sane() {
103 let config = Config::default();
104 assert_ne!(config.max_connections, 0);
105 assert_eq!(config.connect_timeout, 5);
106 }
107}