rocket_db_pools_community/
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/// # This option is only supported by the `sqlx_sqlite` driver.
25/// extensions = ["memvfs", "rot13"]
26/// ```
27///
28/// Alternatively, a custom provider can be used. For example, a custom `Figment`
29/// with a global `databases.name` configuration:
30///
31/// ```rust
32/// # extern crate rocket_db_pools_community as rocket_db_pools;
33/// # use rocket::launch;
34/// #[launch]
35/// fn rocket() -> _ {
36///     let figment = rocket::Config::figment()
37///         .merge(("databases.name", rocket_db_pools::Config {
38///             url: "db:specific@config&url".into(),
39///             min_connections: None,
40///             max_connections: 1024,
41///             connect_timeout: 3,
42///             idle_timeout: None,
43///             extensions: None,
44///         }));
45///
46///     rocket::custom(figment)
47/// }
48/// ```
49///
50/// For general information on configuration in Rocket, see [`rocket::config`].
51/// For higher-level details on configuring a database, see the [crate-level
52/// docs](crate#configuration).
53// NOTE: Defaults provided by the figment created in the `Initializer` fairing.
54#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
55#[serde(crate = "rocket::serde")]
56pub struct Config {
57    /// Database-specific connection and configuration URL.
58    ///
59    /// The format of the URL is database specific; consult your database's
60    /// documentation.
61    pub url: String,
62    /// Minimum number of connections to maintain in the pool.
63    ///
64    /// **Note:** `deadpool` drivers do not support and thus ignore this value.
65    ///
66    /// _Default:_ `None`.
67    pub min_connections: Option<u32>,
68    /// Maximum number of connections to maintain in the pool.
69    ///
70    /// _Default:_ `workers * 4`.
71    pub max_connections: usize,
72    /// Number of seconds to wait for a connection before timing out.
73    ///
74    /// If the timeout elapses before a connection can be made or retrieved from
75    /// a pool, an error is returned.
76    ///
77    /// _Default:_ `5`.
78    pub connect_timeout: u64,
79    /// Maximum number of seconds to keep a connection alive for.
80    ///
81    /// After a connection is established, it is maintained in a pool for
82    /// efficient connection retrieval. When an `idle_timeout` is set, that
83    /// connection will be closed after the timeout elapses. If an
84    /// `idle_timeout` is not specified, the behavior is driver specific but
85    /// typically defaults to keeping a connection active indefinitely.
86    ///
87    /// _Default:_ `None`.
88    pub idle_timeout: Option<u64>,
89    /// A list of database extensions to load at run-time.
90    ///
91    /// **Note:** Only the `sqlx_sqlite` driver supports this option (for SQLite
92    /// extensions) at this time. All other drivers ignore this option.
93    ///
94    /// _Default:_ `None`.
95    pub extensions: Option<Vec<String>>,
96}
97
98impl Default for Config {
99    fn default() -> Self {
100        Self {
101            url: Default::default(),
102            min_connections: Default::default(),
103            max_connections: rocket::Config::default().workers * 4,
104            connect_timeout: 5,
105            idle_timeout: Default::default(),
106            extensions: Default::default(),
107        }
108    }
109}
110
111#[cfg(test)]
112mod tests {
113    use super::Config;
114
115    #[test]
116    fn default_values_sane() {
117        let config = Config::default();
118        assert_ne!(config.max_connections, 0);
119        assert_eq!(config.connect_timeout, 5);
120    }
121}
rocket_db_pools_community/config.rs

rocket_db_pools_community/
config.rs
