postgres/
config.rs

1//! Connection configuration.
2
3use crate::connection::Connection;
4use crate::Client;
5use log::info;
6use std::fmt;
7use std::net::IpAddr;
8use std::path::Path;
9use std::str::FromStr;
10use std::sync::Arc;
11use std::time::Duration;
12use tokio::runtime;
13#[doc(inline)]
14pub use tokio_postgres::config::{
15    ChannelBinding, Host, LoadBalanceHosts, SslMode, SslNegotiation, TargetSessionAttrs,
16};
17use tokio_postgres::error::DbError;
18use tokio_postgres::tls::{MakeTlsConnect, TlsConnect};
19use tokio_postgres::{Error, Socket};
20
21/// Connection configuration.
22///
23/// Configuration can be parsed from libpq-style connection strings. These strings come in two formats:
24///
25/// # Key-Value
26///
27/// This format consists of space-separated key-value pairs. Values which are either the empty string or contain
28/// whitespace should be wrapped in `'`. `'` and `\` characters should be backslash-escaped.
29///
30/// ## Keys
31///
32/// * `user` - The username to authenticate with. Defaults to the user executing this process.
33/// * `password` - The password to authenticate with.
34/// * `dbname` - The name of the database to connect to. Defaults to the username.
35/// * `options` - Command line options used to configure the server.
36/// * `application_name` - Sets the `application_name` parameter on the server.
37/// * `sslmode` - Controls usage of TLS. If set to `disable`, TLS will not be used. If set to `prefer`, TLS will be used
38///     if available, but not used otherwise. If set to `require`, TLS will be forced to be used. Defaults to `prefer`.
39/// * `host` - The host to connect to. On Unix platforms, if the host starts with a `/` character it is treated as the
40///     path to the directory containing Unix domain sockets. Otherwise, it is treated as a hostname. Multiple hosts
41///     can be specified, separated by commas. Each host will be tried in turn when connecting. Required if connecting
42///     with the `connect` method.
43/// * `sslnegotiation` - TLS negotiation method. If set to `direct`, the client will perform direct TLS handshake, this only works for PostgreSQL 17 and newer.
44///     Note that you will need to setup ALPN of TLS client configuration to `postgresql` when using direct TLS.
45///     If set to `postgres`, the default value, it follows original postgres wire protocol to perform the negotiation.
46/// * `hostaddr` - Numeric IP address of host to connect to. This should be in the standard IPv4 address format,
47///     e.g., 172.28.40.9. If your machine supports IPv6, you can also use those addresses.
48///     If this parameter is not specified, the value of `host` will be looked up to find the corresponding IP address,
49///     or if host specifies an IP address, that value will be used directly.
50///     Using `hostaddr` allows the application to avoid a host name look-up, which might be important in applications
51///     with time constraints. However, a host name is required for TLS certificate verification.
52///     Specifically:
53///         * If `hostaddr` is specified without `host`, the value for `hostaddr` gives the server network address.
54///             The connection attempt will fail if the authentication method requires a host name;
55///         * If `host` is specified without `hostaddr`, a host name lookup occurs;
56///         * If both `host` and `hostaddr` are specified, the value for `hostaddr` gives the server network address.
57///             The value for `host` is ignored unless the authentication method requires it,
58///             in which case it will be used as the host name.
59/// * `port` - The port to connect to. Multiple ports can be specified, separated by commas. The number of ports must be
60///     either 1, in which case it will be used for all hosts, or the same as the number of hosts. Defaults to 5432 if
61///     omitted or the empty string.
62/// * `connect_timeout` - The time limit in seconds applied to each socket-level connection attempt. Note that hostnames
63///     can resolve to multiple IP addresses, and this limit is applied to each address. Defaults to no timeout.
64/// * `tcp_user_timeout` - The time limit that transmitted data may remain unacknowledged before a connection is forcibly closed.
65///     This is ignored for Unix domain socket connections. It is only supported on systems where TCP_USER_TIMEOUT is available
66///     and will default to the system default if omitted or set to 0; on other systems, it has no effect.
67/// * `keepalives` - Controls the use of TCP keepalive. A value of 0 disables keepalive and nonzero integers enable it.
68///     This option is ignored when connecting with Unix sockets. Defaults to on.
69/// * `keepalives_idle` - The number of seconds of inactivity after which a keepalive message is sent to the server.
70///     This option is ignored when connecting with Unix sockets. Defaults to 2 hours.
71/// * `keepalives_interval` - The time interval between TCP keepalive probes.
72///     This option is ignored when connecting with Unix sockets.
73/// * `keepalives_retries` - The maximum number of TCP keepalive probes that will be sent before dropping a connection.
74///     This option is ignored when connecting with Unix sockets.
75/// * `target_session_attrs` - Specifies requirements of the session. If set to `read-write`, the client will check that
76///     the `transaction_read_write` session parameter is set to `on`. This can be used to connect to the primary server
77///     in a database cluster as opposed to the secondary read-only mirrors. Defaults to `all`.
78/// * `channel_binding` - Controls usage of channel binding in the authentication process. If set to `disable`, channel
79///     binding will not be used. If set to `prefer`, channel binding will be used if available, but not used otherwise.
80///     If set to `require`, the authentication process will fail if channel binding is not used. Defaults to `prefer`.
81/// * `load_balance_hosts` - Controls the order in which the client tries to connect to the available hosts and
82///     addresses. Once a connection attempt is successful no other hosts and addresses will be tried. This parameter
83///     is typically used in combination with multiple host names or a DNS record that returns multiple IPs. If set to
84///     `disable`, hosts and addresses will be tried in the order provided. If set to `random`, hosts will be tried
85///     in a random order, and the IP addresses resolved from a hostname will also be tried in a random order. Defaults
86///     to `disable`.
87///
88/// ## Examples
89///
90/// ```not_rust
91/// host=localhost user=postgres connect_timeout=10 keepalives=0
92/// ```
93///
94/// ```not_rust
95/// host=/var/lib/postgresql,localhost port=1234 user=postgres password='password with spaces'
96/// ```
97///
98/// ```not_rust
99/// host=host1,host2,host3 port=1234,,5678 hostaddr=127.0.0.1,127.0.0.2,127.0.0.3 user=postgres target_session_attrs=read-write
100/// ```
101///
102/// ```not_rust
103/// host=host1,host2,host3 port=1234,,5678 user=postgres target_session_attrs=read-write
104/// ```
105///
106/// # Url
107///
108/// This format resembles a URL with a scheme of either `postgres://` or `postgresql://`. All components are optional,
109/// and the format accepts query parameters for all of the key-value pairs described in the section above. Multiple
110/// host/port pairs can be comma-separated. Unix socket paths in the host section of the URL should be percent-encoded,
111/// as the path component of the URL specifies the database name.
112///
113/// ## Examples
114///
115/// ```not_rust
116/// postgresql://user@localhost
117/// ```
118///
119/// ```not_rust
120/// postgresql://user:password@%2Fvar%2Flib%2Fpostgresql/mydb?connect_timeout=10
121/// ```
122///
123/// ```not_rust
124/// postgresql://user@host1:1234,host2,host3:5678?target_session_attrs=read-write
125/// ```
126///
127/// ```not_rust
128/// postgresql:///mydb?user=user&host=/var/lib/postgresql
129/// ```
130#[derive(Clone)]
131pub struct Config {
132    config: tokio_postgres::Config,
133    notice_callback: Arc<dyn Fn(DbError) + Send + Sync>,
134}
135
136impl fmt::Debug for Config {
137    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
138        fmt.debug_struct("Config")
139            .field("config", &self.config)
140            .finish()
141    }
142}
143
144impl Default for Config {
145    fn default() -> Config {
146        Config::new()
147    }
148}
149
150impl Config {
151    /// Creates a new configuration.
152    pub fn new() -> Config {
153        tokio_postgres::Config::new().into()
154    }
155
156    /// Sets the user to authenticate with.
157    ///
158    /// If the user is not set, then this defaults to the user executing this process.
159    pub fn user(&mut self, user: &str) -> &mut Config {
160        self.config.user(user);
161        self
162    }
163
164    /// Gets the user to authenticate with, if one has been configured with
165    /// the `user` method.
166    pub fn get_user(&self) -> Option<&str> {
167        self.config.get_user()
168    }
169
170    /// Sets the password to authenticate with.
171    pub fn password<T>(&mut self, password: T) -> &mut Config
172    where
173        T: AsRef<[u8]>,
174    {
175        self.config.password(password);
176        self
177    }
178
179    /// Gets the password to authenticate with, if one has been configured with
180    /// the `password` method.
181    pub fn get_password(&self) -> Option<&[u8]> {
182        self.config.get_password()
183    }
184
185    /// Sets the name of the database to connect to.
186    ///
187    /// Defaults to the user.
188    pub fn dbname(&mut self, dbname: &str) -> &mut Config {
189        self.config.dbname(dbname);
190        self
191    }
192
193    /// Gets the name of the database to connect to, if one has been configured
194    /// with the `dbname` method.
195    pub fn get_dbname(&self) -> Option<&str> {
196        self.config.get_dbname()
197    }
198
199    /// Sets command line options used to configure the server.
200    pub fn options(&mut self, options: &str) -> &mut Config {
201        self.config.options(options);
202        self
203    }
204
205    /// Gets the command line options used to configure the server, if the
206    /// options have been set with the `options` method.
207    pub fn get_options(&self) -> Option<&str> {
208        self.config.get_options()
209    }
210
211    /// Sets the value of the `application_name` runtime parameter.
212    pub fn application_name(&mut self, application_name: &str) -> &mut Config {
213        self.config.application_name(application_name);
214        self
215    }
216
217    /// Gets the value of the `application_name` runtime parameter, if it has
218    /// been set with the `application_name` method.
219    pub fn get_application_name(&self) -> Option<&str> {
220        self.config.get_application_name()
221    }
222
223    /// Sets the SSL configuration.
224    ///
225    /// Defaults to `prefer`.
226    pub fn ssl_mode(&mut self, ssl_mode: SslMode) -> &mut Config {
227        self.config.ssl_mode(ssl_mode);
228        self
229    }
230
231    /// Gets the SSL configuration.
232    pub fn get_ssl_mode(&self) -> SslMode {
233        self.config.get_ssl_mode()
234    }
235
236    /// Sets the SSL negotiation method
237    pub fn ssl_negotiation(&mut self, ssl_negotiation: SslNegotiation) -> &mut Config {
238        self.config.ssl_negotiation(ssl_negotiation);
239        self
240    }
241
242    /// Gets the SSL negotiation method
243    pub fn get_ssl_negotiation(&self) -> SslNegotiation {
244        self.config.get_ssl_negotiation()
245    }
246
247    /// Adds a host to the configuration.
248    ///
249    /// Multiple hosts can be specified by calling this method multiple times, and each will be tried in order. On Unix
250    /// systems, a host starting with a `/` is interpreted as a path to a directory containing Unix domain sockets.
251    /// There must be either no hosts, or the same number of hosts as hostaddrs.
252    pub fn host(&mut self, host: &str) -> &mut Config {
253        self.config.host(host);
254        self
255    }
256
257    /// Gets the hosts that have been added to the configuration with `host`.
258    pub fn get_hosts(&self) -> &[Host] {
259        self.config.get_hosts()
260    }
261
262    /// Gets the hostaddrs that have been added to the configuration with `hostaddr`.
263    pub fn get_hostaddrs(&self) -> &[IpAddr] {
264        self.config.get_hostaddrs()
265    }
266
267    /// Adds a Unix socket host to the configuration.
268    ///
269    /// Unlike `host`, this method allows non-UTF8 paths.
270    #[cfg(unix)]
271    pub fn host_path<T>(&mut self, host: T) -> &mut Config
272    where
273        T: AsRef<Path>,
274    {
275        self.config.host_path(host);
276        self
277    }
278
279    /// Adds a hostaddr to the configuration.
280    ///
281    /// Multiple hostaddrs can be specified by calling this method multiple times, and each will be tried in order.
282    /// There must be either no hostaddrs, or the same number of hostaddrs as hosts.
283    pub fn hostaddr(&mut self, hostaddr: IpAddr) -> &mut Config {
284        self.config.hostaddr(hostaddr);
285        self
286    }
287
288    /// Adds a port to the configuration.
289    ///
290    /// Multiple ports can be specified by calling this method multiple times. There must either be no ports, in which
291    /// case the default of 5432 is used, a single port, in which it is used for all hosts, or the same number of ports
292    /// as hosts.
293    pub fn port(&mut self, port: u16) -> &mut Config {
294        self.config.port(port);
295        self
296    }
297
298    /// Gets the ports that have been added to the configuration with `port`.
299    pub fn get_ports(&self) -> &[u16] {
300        self.config.get_ports()
301    }
302
303    /// Sets the timeout applied to socket-level connection attempts.
304    ///
305    /// Note that hostnames can resolve to multiple IP addresses, and this timeout will apply to each address of each
306    /// host separately. Defaults to no limit.
307    pub fn connect_timeout(&mut self, connect_timeout: Duration) -> &mut Config {
308        self.config.connect_timeout(connect_timeout);
309        self
310    }
311
312    /// Gets the connection timeout, if one has been set with the
313    /// `connect_timeout` method.
314    pub fn get_connect_timeout(&self) -> Option<&Duration> {
315        self.config.get_connect_timeout()
316    }
317
318    /// Sets the TCP user timeout.
319    ///
320    /// This is ignored for Unix domain socket connections. It is only supported on systems where
321    /// TCP_USER_TIMEOUT is available and will default to the system default if omitted or set to 0;
322    /// on other systems, it has no effect.
323    pub fn tcp_user_timeout(&mut self, tcp_user_timeout: Duration) -> &mut Config {
324        self.config.tcp_user_timeout(tcp_user_timeout);
325        self
326    }
327
328    /// Gets the TCP user timeout, if one has been set with the
329    /// `user_timeout` method.
330    pub fn get_tcp_user_timeout(&self) -> Option<&Duration> {
331        self.config.get_tcp_user_timeout()
332    }
333
334    /// Controls the use of TCP keepalive.
335    ///
336    /// This is ignored for Unix domain socket connections. Defaults to `true`.
337    pub fn keepalives(&mut self, keepalives: bool) -> &mut Config {
338        self.config.keepalives(keepalives);
339        self
340    }
341
342    /// Reports whether TCP keepalives will be used.
343    pub fn get_keepalives(&self) -> bool {
344        self.config.get_keepalives()
345    }
346
347    /// Sets the amount of idle time before a keepalive packet is sent on the connection.
348    ///
349    /// This is ignored for Unix domain sockets, or if the `keepalives` option is disabled. Defaults to 2 hours.
350    pub fn keepalives_idle(&mut self, keepalives_idle: Duration) -> &mut Config {
351        self.config.keepalives_idle(keepalives_idle);
352        self
353    }
354
355    /// Gets the configured amount of idle time before a keepalive packet will
356    /// be sent on the connection.
357    pub fn get_keepalives_idle(&self) -> Duration {
358        self.config.get_keepalives_idle()
359    }
360
361    /// Sets the time interval between TCP keepalive probes.
362    /// On Windows, this sets the value of the tcp_keepalive struct’s keepaliveinterval field.
363    ///
364    /// This is ignored for Unix domain sockets, or if the `keepalives` option is disabled.
365    pub fn keepalives_interval(&mut self, keepalives_interval: Duration) -> &mut Config {
366        self.config.keepalives_interval(keepalives_interval);
367        self
368    }
369
370    /// Gets the time interval between TCP keepalive probes.
371    pub fn get_keepalives_interval(&self) -> Option<Duration> {
372        self.config.get_keepalives_interval()
373    }
374
375    /// Sets the maximum number of TCP keepalive probes that will be sent before dropping a connection.
376    ///
377    /// This is ignored for Unix domain sockets, or if the `keepalives` option is disabled.
378    pub fn keepalives_retries(&mut self, keepalives_retries: u32) -> &mut Config {
379        self.config.keepalives_retries(keepalives_retries);
380        self
381    }
382
383    /// Gets the maximum number of TCP keepalive probes that will be sent before dropping a connection.
384    pub fn get_keepalives_retries(&self) -> Option<u32> {
385        self.config.get_keepalives_retries()
386    }
387
388    /// Sets the requirements of the session.
389    ///
390    /// This can be used to connect to the primary server in a clustered database rather than one of the read-only
391    /// secondary servers. Defaults to `Any`.
392    pub fn target_session_attrs(
393        &mut self,
394        target_session_attrs: TargetSessionAttrs,
395    ) -> &mut Config {
396        self.config.target_session_attrs(target_session_attrs);
397        self
398    }
399
400    /// Gets the requirements of the session.
401    pub fn get_target_session_attrs(&self) -> TargetSessionAttrs {
402        self.config.get_target_session_attrs()
403    }
404
405    /// Sets the channel binding behavior.
406    ///
407    /// Defaults to `prefer`.
408    pub fn channel_binding(&mut self, channel_binding: ChannelBinding) -> &mut Config {
409        self.config.channel_binding(channel_binding);
410        self
411    }
412
413    /// Gets the channel binding behavior.
414    pub fn get_channel_binding(&self) -> ChannelBinding {
415        self.config.get_channel_binding()
416    }
417
418    /// Sets the host load balancing behavior.
419    ///
420    /// Defaults to `disable`.
421    pub fn load_balance_hosts(&mut self, load_balance_hosts: LoadBalanceHosts) -> &mut Config {
422        self.config.load_balance_hosts(load_balance_hosts);
423        self
424    }
425
426    /// Gets the host load balancing behavior.
427    pub fn get_load_balance_hosts(&self) -> LoadBalanceHosts {
428        self.config.get_load_balance_hosts()
429    }
430
431    /// Sets the notice callback.
432    ///
433    /// This callback will be invoked with the contents of every
434    /// [`AsyncMessage::Notice`] that is received by the connection. Notices use
435    /// the same structure as errors, but they are not "errors" per-se.
436    ///
437    /// Notices are distinct from notifications, which are instead accessible
438    /// via the [`Notifications`] API.
439    ///
440    /// [`AsyncMessage::Notice`]: tokio_postgres::AsyncMessage::Notice
441    /// [`Notifications`]: crate::Notifications
442    pub fn notice_callback<F>(&mut self, f: F) -> &mut Config
443    where
444        F: Fn(DbError) + Send + Sync + 'static,
445    {
446        self.notice_callback = Arc::new(f);
447        self
448    }
449
450    /// Opens a connection to a PostgreSQL database.
451    pub fn connect<T>(&self, tls: T) -> Result<Client, Error>
452    where
453        T: MakeTlsConnect<Socket> + 'static + Send,
454        T::TlsConnect: Send,
455        T::Stream: Send,
456        <T::TlsConnect as TlsConnect<Socket>>::Future: Send,
457    {
458        let runtime = runtime::Builder::new_current_thread()
459            .enable_all()
460            .build()
461            .unwrap(); // FIXME don't unwrap
462
463        let (client, connection) = runtime.block_on(self.config.connect(tls))?;
464
465        let connection = Connection::new(runtime, connection, self.notice_callback.clone());
466        Ok(Client::new(connection, client))
467    }
468}
469
470impl FromStr for Config {
471    type Err = Error;
472
473    fn from_str(s: &str) -> Result<Config, Error> {
474        s.parse::<tokio_postgres::Config>().map(Config::from)
475    }
476}
477
478impl From<tokio_postgres::Config> for Config {
479    fn from(config: tokio_postgres::Config) -> Config {
480        Config {
481            config,
482            notice_callback: Arc::new(|notice| {
483                info!("{}: {}", notice.severity(), notice.message())
484            }),
485        }
486    }
487}