Skip to main content

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}