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. Required.
  • 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.
  • sslcert - Location of the client SSL certificate file.
  • sslkey - Location for the secret key file used for the client certificate.
  • 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, verify-ca, or verify-full, TLS will be forced to be used. Defaults to prefer.
  • sslrootcert - Location of SSL certificate authority (CA) certificate.
  • 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.
  • 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.
  • 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.
  • 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.

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 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

Creates a new configuration.

Sets the user to authenticate with.

Required.

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

Sets the password to authenticate with.

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

Sets the name of the database to connect to.

Defaults to the user.

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

Sets command line options used to configure the server.

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

Sets the value of the application_name runtime parameter.

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

Sets the location of the client SSL certificate file.

Defaults to None.

Gets the location of the client SSL certificate file.

Sets the location of the secret key file used for the client certificate.

Defaults to None.

Gets the location of the secret key file used for the client certificate.

Sets the SSL configuration.

Defaults to prefer.

Gets the SSL configuration.

Sets the location of SSL certificate authority (CA) certificate.

Defaults to None.

Gets the location of SSL certificate authority (CA) certificate.

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.

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

Adds a Unix socket host to the configuration.

Unlike host, this method allows non-UTF8 paths.

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.

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

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.

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

Controls the use of TCP keepalive.

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

Reports whether TCP keepalives will be used.

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.

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

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.

Gets the requirements of the session.

Sets the channel binding behavior.

Defaults to prefer.

Gets the channel binding behavior.

Set replication mode.

Get replication mode.

Opens a connection to a PostgreSQL database.

Requires the runtime Cargo feature (enabled by default).

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

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

The associated error which can be returned from parsing.

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

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

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

Should always be Self

The resulting type after obtaining ownership.

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

🔬 This is a nightly-only experimental API. (toowned_clone_into)

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

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more