Struct tokio_postgres::config::Config

source ·
pub struct Config { /* private fields */ }
Expand description

Connection configuration.

Configuration can be parsed from libpq-style connection strings. These strings come in two formats:

§Key-Value

This format consists of space-separated key-value pairs. Values which are either the empty string or contain whitespace should be wrapped in '. ' and \ characters should be backslash-escaped.

§Keys

  • user - The username to authenticate with. Defaults to the user executing this process.
  • password - The password to authenticate with.
  • dbname - The name of the database to connect to. Defaults to the username.
  • options - Command line options used to configure the server.
  • application_name - Sets the application_name parameter on the server.
  • sslmode - Controls usage of TLS. If set to disable, TLS will not be used. If set to prefer, TLS will be used if available, but not used otherwise. If set to require, TLS will be forced to be used. Defaults to prefer.
  • host - The host to connect to. On Unix platforms, if the host starts with a / character it is treated as the path to the directory containing Unix domain sockets. Otherwise, it is treated as a hostname. Multiple hosts can be specified, separated by commas. Each host will be tried in turn when connecting. Required if connecting with the connect method.
  • hostaddr - Numeric IP address of host to connect to. This should be in the standard IPv4 address format, e.g., 172.28.40.9. If your machine supports IPv6, you can also use those addresses. If this parameter is not specified, the value of host will be looked up to find the corresponding IP address, or if host specifies an IP address, that value will be used directly. Using hostaddr allows the application to avoid a host name look-up, which might be important in applications with time constraints. However, a host name is required for TLS certificate verification. Specifically: * If hostaddr is specified without host, the value for hostaddr gives the server network address. The connection attempt will fail if the authentication method requires a host name; * If host is specified without hostaddr, a host name lookup occurs; * If both host and hostaddr are specified, the value for hostaddr gives the server network address. The value for host is ignored unless the authentication method requires it, in which case it will be used as the host name.
  • port - The port to connect to. Multiple ports can be specified, separated by commas. The number of ports must be either 1, in which case it will be used for all hosts, or the same as the number of hosts. Defaults to 5432 if omitted or the empty string.
  • connect_timeout - The time limit in seconds applied to each socket-level connection attempt. Note that hostnames can resolve to multiple IP addresses, and this limit is applied to each address. Defaults to no timeout.
  • tcp_user_timeout - The time limit that transmitted data may remain unacknowledged before a connection is forcibly closed. This is ignored for Unix domain socket connections. It is only supported on systems where TCP_USER_TIMEOUT is available and will default to the system default if omitted or set to 0; on other systems, it has no effect.
  • keepalives - Controls the use of TCP keepalive. A value of 0 disables keepalive and nonzero integers enable it. This option is ignored when connecting with Unix sockets. Defaults to on.
  • keepalives_idle - The number of seconds of inactivity after which a keepalive message is sent to the server. This option is ignored when connecting with Unix sockets. Defaults to 2 hours.
  • keepalives_interval - The time interval between TCP keepalive probes. This option is ignored when connecting with Unix sockets.
  • keepalives_retries - The maximum number of TCP keepalive probes that will be sent before dropping a connection. This option is ignored when connecting with Unix sockets.
  • target_session_attrs - Specifies requirements of the session. If set to read-write, the client will check that the transaction_read_write session parameter is set to on. This can be used to connect to the primary server in a database cluster as opposed to the secondary read-only mirrors. Defaults to all.
  • channel_binding - Controls usage of channel binding in the authentication process. If set to disable, channel binding will not be used. If set to prefer, channel binding will be used if available, but not used otherwise. If set to require, the authentication process will fail if channel binding is not used. Defaults to prefer.
  • load_balance_hosts - Controls the order in which the client tries to connect to the available hosts and addresses. Once a connection attempt is successful no other hosts and addresses will be tried. This parameter is typically used in combination with multiple host names or a DNS record that returns multiple IPs. If set to disable, hosts and addresses will be tried in the order provided. If set to random, hosts will be tried in a random order, and the IP addresses resolved from a hostname will also be tried in a random order. Defaults to disable.

§Examples

host=localhost user=postgres connect_timeout=10 keepalives=0
host=/var/lib/postgresql,localhost port=1234 user=postgres password='password with spaces'
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
host=host1,host2,host3 port=1234,,5678 user=postgres target_session_attrs=read-write

§Url

This format resembles a URL with a scheme of either postgres:// or postgresql://. All components are optional, and the format accepts query parameters for all of the key-value pairs described in the section above. Multiple host/port pairs can be comma-separated. Unix socket paths in the host section of the URL should be percent-encoded, as the path component of the URL specifies the database name.

§Examples

postgresql://user@localhost
postgresql://user:password@%2Fvar%2Flib%2Fpostgresql/mydb?connect_timeout=10
postgresql://user@host1:1234,host2,host3:5678?target_session_attrs=read-write
postgresql:///mydb?user=user&host=/var/lib/postgresql

Implementations§

source§

impl Config

source

pub fn new() -> Config

Creates a new configuration.

source

pub fn user(&mut self, user: impl Into<String>) -> &mut Config

Sets the user to authenticate with.

Defaults to the user executing this process.

source

pub fn get_user(&self) -> Option<&str>

Gets the user to authenticate with, if one has been configured with the user method.

source

pub fn password<T>(&mut self, password: T) -> &mut Config
where T: AsRef<[u8]>,

Sets the password to authenticate with.

source

pub fn get_password(&self) -> Option<&[u8]>

Gets the password to authenticate with, if one has been configured with the password method.

source

pub fn dbname(&mut self, dbname: impl Into<String>) -> &mut Config

Sets the name of the database to connect to.

Defaults to the user.

source

pub fn get_dbname(&self) -> Option<&str>

Gets the name of the database to connect to, if one has been configured with the dbname method.

source

pub fn options(&mut self, options: impl Into<String>) -> &mut Config

Sets command line options used to configure the server.

source

pub fn get_options(&self) -> Option<&str>

Gets the command line options used to configure the server, if the options have been set with the options method.

source

pub fn application_name( &mut self, application_name: impl Into<String>, ) -> &mut Config

Sets the value of the application_name runtime parameter.

source

pub fn get_application_name(&self) -> Option<&str>

Gets the value of the application_name runtime parameter, if it has been set with the application_name method.

source

pub fn ssl_mode(&mut self, ssl_mode: SslMode) -> &mut Config

Sets the SSL configuration.

Defaults to prefer.

source

pub fn get_ssl_mode(&self) -> SslMode

Gets the SSL configuration.

source

pub fn host(&mut self, host: impl Into<String>) -> &mut Config

Adds a host to the configuration.

Multiple hosts can be specified by calling this method multiple times, and each will be tried in order. On Unix systems, a host starting with a / is interpreted as a path to a directory containing Unix domain sockets. There must be either no hosts, or the same number of hosts as hostaddrs.

source

pub fn get_hosts(&self) -> &[Host]

Gets the hosts that have been added to the configuration with host.

source

pub fn get_hostaddrs(&self) -> &[IpAddr]

Gets the hostaddrs that have been added to the configuration with hostaddr.

source

pub fn host_path<T>(&mut self, host: T) -> &mut Config
where T: AsRef<Path>,

Adds a Unix socket host to the configuration.

Unlike host, this method allows non-UTF8 paths.

source

pub fn hostaddr(&mut self, hostaddr: IpAddr) -> &mut Config

Adds a hostaddr to the configuration.

Multiple hostaddrs can be specified by calling this method multiple times, and each will be tried in order. There must be either no hostaddrs, or the same number of hostaddrs as hosts.

source

pub fn port(&mut self, port: u16) -> &mut Config

Adds a port to the configuration.

Multiple ports can be specified by calling this method multiple times. There must either be no ports, in which case the default of 5432 is used, a single port, in which it is used for all hosts, or the same number of ports as hosts.

source

pub fn get_ports(&self) -> &[u16]

Gets the ports that have been added to the configuration with port.

source

pub fn connect_timeout(&mut self, connect_timeout: Duration) -> &mut Config

Sets the timeout applied to socket-level connection attempts.

Note that hostnames can resolve to multiple IP addresses, and this timeout will apply to each address of each host separately. Defaults to no limit.

source

pub fn get_connect_timeout(&self) -> Option<&Duration>

Gets the connection timeout, if one has been set with the connect_timeout method.

source

pub fn tcp_user_timeout(&mut self, tcp_user_timeout: Duration) -> &mut Config

Sets the TCP user timeout.

This is ignored for Unix domain socket connections. It is only supported on systems where TCP_USER_TIMEOUT is available and will default to the system default if omitted or set to 0; on other systems, it has no effect.

source

pub fn get_tcp_user_timeout(&self) -> Option<&Duration>

Gets the TCP user timeout, if one has been set with the user_timeout method.

source

pub fn keepalives(&mut self, keepalives: bool) -> &mut Config

Controls the use of TCP keepalive.

This is ignored for Unix domain socket connections. Defaults to true.

source

pub fn get_keepalives(&self) -> bool

Reports whether TCP keepalives will be used.

source

pub fn keepalives_idle(&mut self, keepalives_idle: Duration) -> &mut Config

Sets the amount of idle time before a keepalive packet is sent on the connection.

This is ignored for Unix domain sockets, or if the keepalives option is disabled. Defaults to 2 hours.

source

pub fn get_keepalives_idle(&self) -> Duration

Gets the configured amount of idle time before a keepalive packet will be sent on the connection.

source

pub fn keepalives_interval( &mut self, keepalives_interval: Duration, ) -> &mut Config

Sets the time interval between TCP keepalive probes. On Windows, this sets the value of the tcp_keepalive struct’s keepaliveinterval field.

This is ignored for Unix domain sockets, or if the keepalives option is disabled.

source

pub fn get_keepalives_interval(&self) -> Option<Duration>

Gets the time interval between TCP keepalive probes.

source

pub fn keepalives_retries(&mut self, keepalives_retries: u32) -> &mut Config

Sets the maximum number of TCP keepalive probes that will be sent before dropping a connection.

This is ignored for Unix domain sockets, or if the keepalives option is disabled.

source

pub fn get_keepalives_retries(&self) -> Option<u32>

Gets the maximum number of TCP keepalive probes that will be sent before dropping a connection.

source

pub fn target_session_attrs( &mut self, target_session_attrs: TargetSessionAttrs, ) -> &mut Config

Sets the requirements of the session.

This can be used to connect to the primary server in a clustered database rather than one of the read-only secondary servers. Defaults to Any.

source

pub fn get_target_session_attrs(&self) -> TargetSessionAttrs

Gets the requirements of the session.

source

pub fn channel_binding( &mut self, channel_binding: ChannelBinding, ) -> &mut Config

Sets the channel binding behavior.

Defaults to prefer.

source

pub fn get_channel_binding(&self) -> ChannelBinding

Gets the channel binding behavior.

source

pub fn load_balance_hosts( &mut self, load_balance_hosts: LoadBalanceHosts, ) -> &mut Config

Sets the host load balancing behavior.

Defaults to disable.

source

pub fn get_load_balance_hosts(&self) -> LoadBalanceHosts

Gets the host load balancing behavior.

source

pub async fn connect<T>( &self, tls: T, ) -> Result<(Client, Connection<Socket, T::Stream>), Error>

Opens a connection to a PostgreSQL database.

Requires the runtime Cargo feature (enabled by default).

source

pub async fn connect_raw<S, T>( &self, stream: S, tls: T, ) -> Result<(Client, Connection<S, T::Stream>), Error>
where S: AsyncRead + AsyncWrite + Unpin, T: TlsConnect<S>,

Connects to a PostgreSQL database over an arbitrary stream.

All of the settings other than user, password, dbname, options, and application_name name are ignored.

Trait Implementations§

source§

impl Clone for Config

source§

fn clone(&self) -> Config

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for Config

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Default for Config

source§

fn default() -> Config

Returns the “default value” for a type. Read more
source§

impl FromStr for Config

§

type Err = Error

The associated error which can be returned from parsing.
source§

fn from_str(s: &str) -> Result<Config, Error>

Parses a string s to return a value of this type. Read more
source§

impl PartialEq for Config

source§

fn eq(&self, other: &Config) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Eq for Config

source§

impl StructuralPartialEq for Config

Auto Trait Implementations§

§

impl Freeze for Config

§

impl RefUnwindSafe for Config

§

impl Send for Config

§

impl Sync for Config

§

impl Unpin for Config

§

impl UnwindSafe for Config

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V