tang_rs/
builder.rs

1use core::time::Duration;
2
3use crate::manager::Manager;
4use crate::pool::Pool;
5
6pub struct Builder {
7    pub(crate) max_size: usize,
8    pub(crate) min_idle: usize,
9    pub(crate) always_check: bool,
10    pub(crate) use_gc: bool,
11    pub(crate) max_lifetime: Option<Duration>,
12    pub(crate) idle_timeout: Option<Duration>,
13    pub(crate) connection_timeout: Duration,
14    pub(crate) wait_timeout: Duration,
15    pub(crate) reaper_rate: Duration,
16}
17
18impl Default for Builder {
19    fn default() -> Self {
20        Builder {
21            max_size: 10,
22            min_idle: 1,
23            always_check: true,
24            use_gc: false,
25            max_lifetime: Some(Duration::from_secs(30 * 60)),
26            idle_timeout: Some(Duration::from_secs(10 * 60)),
27            connection_timeout: Duration::from_secs(10),
28            wait_timeout: Duration::from_secs(20),
29            reaper_rate: Duration::from_secs(15),
30        }
31    }
32}
33
34impl Builder {
35    pub fn new() -> Builder {
36        Default::default()
37    }
38
39    pub fn max_size(mut self, max_size: usize) -> Builder {
40        self.max_size = max_size;
41        self
42    }
43
44    pub fn min_idle(mut self, min_idle: usize) -> Builder {
45        self.min_idle = min_idle;
46        self
47    }
48
49    /// If true, the health of a connection will be verified when checkout.
50    ///
51    /// This check uses `Builder`'s `connection_timeout` setting to cancel the check and return a timeout error.
52    ///
53    /// Defaults to true.
54    pub fn always_check(mut self, always_check: bool) -> Builder {
55        self.always_check = always_check;
56        self
57    }
58
59    /// If true, the pending connections that last for too long will be removed.( 6 times the `connection_timeout` duration)
60    ///
61    /// This is a placeholder feature. it works fine but in most cases it's not necessary or useful.
62    ///
63    /// Defaults to false.
64    pub fn use_gc(mut self, use_gc: bool) -> Builder {
65        self.use_gc = use_gc;
66        self
67    }
68
69    /// Sets the maximum lifetime of connections in the pool.
70    ///
71    /// If set, connections will be closed at the next reaping after surviving
72    /// past this duration.
73    ///
74    /// If a connection reaches its maximum lifetime while checked out it will be
75    /// closed when it is returned to the pool.
76    ///
77    /// Defaults to 30 minutes.
78    pub fn max_lifetime(mut self, max_lifetime: Option<Duration>) -> Builder {
79        self.max_lifetime = max_lifetime;
80        self
81    }
82
83    /// Sets the idle timeout used by the pool.
84    ///
85    /// If set, idle connections in excess of `min_idle` will be closed at the
86    /// next reaping after remaining idle past this duration.
87    ///
88    /// Defaults to 10 minutes.
89    pub fn idle_timeout(mut self, idle_timeout: Option<Duration>) -> Builder {
90        self.idle_timeout = idle_timeout;
91        self
92    }
93
94    /// Sets the connection reaper rate.
95    ///
96    /// The connection that are idle and live beyond the time gate will be dropped.
97    ///
98    /// Default 15 seconds.(no guarantee as we don't force lock the pool)
99    pub fn reaper_rate(mut self, reaper_rate: Duration) -> Builder {
100        self.reaper_rate = reaper_rate;
101        self
102    }
103
104    /// Sets the connection timeout used by the pool.
105    ///
106    /// Attempt to establish new connection to database will be canceled and return a timeout error if this Duration passed.
107    ///
108    /// It's recommended to set this duration the same or a bit longer than your database connection timeout setting.
109    ///
110    /// Default 10 seconds.
111    pub fn connection_timeout(mut self, connection_timeout: Duration) -> Builder {
112        self.connection_timeout = connection_timeout;
113        self
114    }
115
116    /// Sets the wait timeout used by the queue.
117    ///
118    /// Similar to `connection_timeout`. A timeout error will return if we wait too long for a connection from pool.
119    ///
120    /// Default 20 seconds
121    pub fn wait_timeout(mut self, wait_timeout: Duration) -> Builder {
122        self.wait_timeout = wait_timeout;
123        self
124    }
125
126    /// Consumes the `Builder`, returning a new, initialized `Pool`.
127    pub async fn build<M: Manager>(self, manager: M) -> Result<Pool<M>, M::Error> {
128        let pool = self.build_uninitialized(manager);
129        pool.init().await?;
130        Ok(pool)
131    }
132
133    /// Consumes the `Builder`, returning a new uninitialized `Pool`.
134    ///
135    /// (`Pool` have no connection and scheduled tasks like connection reaper and garbage collect)
136    pub fn build_uninitialized<M: Manager>(self, manager: M) -> Pool<M> {
137        assert!(
138            self.max_size >= self.min_idle,
139            "min_idle must be no larger than max_size"
140        );
141
142        Pool::new(self, manager)
143    }
144
145    /// expose `reaper_rate` to public.
146    pub fn get_reaper_rate(&self) -> Duration {
147        self.reaper_rate
148    }
149}
tang_rs/builder.rs

tang_rs/
builder.rs
