Struct PgConnectOptions

pub struct PgConnectOptions { /* private fields */ }

Available on crate feature postgres only.

Options and flags which can be used to configure a PostgreSQL connection.

A value of PgConnectOptions can be parsed from a connection URL, as described by libpq.

The general form for a connection URL is:

postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]

The URL scheme designator can be either postgresql:// or postgres://. Each of the URL parts is optional. For defaults, see the next section.

This type also implements FromStr so you can parse it from a string containing a connection URL and then further adjust options if necessary (see example below).

Note that characters not allowed in URLs must be percent-encoded.

Parameters

This API accepts many of the same parameters as libpq; if a parameter is not passed in via URL, it is populated by reading environment variables or choosing customary defaults.

Parameter	Environment Variable	Default / Remarks
user	PGUSER	The whoami of the currently running process.
password	PGPASSWORD	Read from passfile, if it exists.
passfile	PGPASSFILE	~/.pgpass or %APPDATA%\postgresql\pgpass.conf (Windows)
host	PGHOST	See Note: Default Host.
hostaddr	PGHOSTADDR	See Note: Default Host.
port	PGPORT	5432
dbname	PGDATABASE	Unset; defaults to the username server-side.
sslmode	PGSSLMODE	prefer. See PgSslMode for details.
sslrootcert	PGSSLROOTCERT	Unset. See Note: SSL.
sslcert	PGSSLCERT	Unset. See Note: SSL.
sslkey	PGSSLKEY	Unset. See Note: SSL.
options	PGOPTIONS	Unset.
application_name	PGAPPNAME	Unset.

passfile handling may be bypassed using PgConnectOptions::new_without_pgpass().

SQLx-Specific

SQLx also parses some bespoke parameters. These are not configurable by environment variable. Instead, the name is linked to the method to set the value.

Parameter	Default
statement-cache-capacity	100

Example URLs

postgresql://
postgresql://:5433
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/mydb
postgresql://user@localhost
postgresql://user:secret@localhost
postgresql://user:correct%20horse%20battery%20staple@localhost
postgresql://localhost?dbname=mydb&user=postgres&password=postgres

See also Note: Unix Domain Sockets below.

Note: Default Host

If the connection URL does not contain a hostname and PGHOST is not set, this constructor looks for an open Unix domain socket in one of a few standard locations (configured when Postgres is built):

• /var/run/postgresql/.s.PGSQL.{port} (Debian)
• /private/tmp/.s.PGSQL.{port} (macOS when installed through Homebrew)
• /tmp/.s.PGSQL.{port} (default otherwise)

This depends on the value of port being correct. If Postgres is using a port other than the default (5432), port must be set.

If no Unix domain socket is found, localhost is assumed.

Note: this description is updated on a best-effort basis. See default_host() in the same source file as this method for the current behavior.

Note: SSL

Root Certs

If sslrootcert is not set, the default root certificates used depends on Cargo features:

• If tls-native-tls is enabled, the system root certificates are used.
• If tls-rustls-native-roots is enabled, the system root certificates are used.
• Otherwise, TLS roots are populated using the webpki-roots crate.

Environment Variables

Unlike with libpq, the following environment variables may be either a path to a file or a string value containing a PEM-encoded value:

• PGSSLROOTCERT
• PGSSLCERT
• PGSSLKEY

If the string begins with the standard -----BEGIN <CERTIFICATE | PRIVATE KEY>----- header and ends with the standard -----END <CERTIFICATE | PRIVATE KEY>----- footer, it is parsed directly.

This behavior is only implemented for the environment variables, not the URL parameters.

Note: passing the SSL private key via environment variable may be a security risk.

Note: Unix Domain Sockets

If you want to connect to Postgres over a Unix domain socket, you can pass the path to the directory containing the socket as the host parameter.

The final path to the socket will be {host}/.s.PGSQL.{port} as is standard for Postgres.

If you’re passing the domain socket path as the host segment of the URL, forward slashes in the path must be percent-encoded (replacing / with %2F), e.g.:

postgres://%2Fvar%2Frun%2Fpostgresql/dbname

Different port:
postgres://%2Fvar%2Frun%2Fpostgresql:5433/dbname

With username and password:
postgres://user:password@%2Fvar%2Frun%2Fpostgresql/dbname

With username and password, and different port:
postgres://user:password@%2Fvar%2Frun%2Fpostgresql:5432/dbname

Instead, the hostname can be passed in the query segment of the URL, which does not require forward-slashes to be percent-encoded (however, other characters are):

postgres:dbname?host=/var/run/postgresql

Different port:
postgres://:5433/dbname?host=/var/run/postgresql

With username and password:
postgres://user:password@/dbname?host=/var/run/postgresql

With username and password, and different port:
postgres://user:password@:5433/dbname?host=/var/run/postgresql

Example

use sqlx::{Connection, ConnectOptions};
use sqlx::postgres::{PgConnectOptions, PgConnection, PgPool, PgSslMode};

// URL connection string
let conn = PgConnection::connect("postgres://localhost/mydb").await?;

// Manually-constructed options
let conn = PgConnectOptions::new()
    .host("secret-host")
    .port(2525)
    .username("secret-user")
    .password("secret-password")
    .ssl_mode(PgSslMode::Require)
    .connect()
    .await?;

// Modifying options parsed from a string
let mut opts: PgConnectOptions = "postgres://localhost/mydb".parse()?;

// Change the log verbosity level for queries.
// Information about SQL queries is logged at `DEBUG` level by default.
opts = opts.log_statements(log::LevelFilter::Trace);

let pool = PgPool::connect_with(opts).await?;

Implementations

impl PgConnectOptions

pub fn new() -> PgConnectOptions

Create a default set of connection options populated from the current environment.

This behaves as if parsed from the connection string postgres://

See the type-level documentation for details.

pub fn new_without_pgpass() -> PgConnectOptions

Create a default set of connection options without reading from passfile.

Equivalent to PgConnectOptions::new() but passfile is ignored.

See the type-level documentation for details.

pub fn host(self, host: &str) -> PgConnectOptions

Sets the name of the host to connect to.

If a host name begins with a slash, it specifies Unix-domain communication rather than TCP/IP communication; the value is the name of the directory in which the socket file is stored.

The default behavior when host is not specified, or is empty, is to connect to a Unix-domain socket

Example

let options = PgConnectOptions::new()
    .host("localhost");

pub fn port(self, port: u16) -> PgConnectOptions

Sets the port to connect to at the server host.

The default port for PostgreSQL is 5432.

Example

let options = PgConnectOptions::new()
    .port(5432);

pub fn socket(self, path: impl AsRef<Path>) -> PgConnectOptions

Sets a custom path to a directory containing a unix domain socket, switching the connection method from TCP to the corresponding socket.

By default set to None.

pub fn username(self, username: &str) -> PgConnectOptions

Sets the username to connect as.

Defaults to be the same as the operating system name of the user running the application.

Example

let options = PgConnectOptions::new()
    .username("postgres");

pub fn password(self, password: &str) -> PgConnectOptions

Sets the password to use if the server demands password authentication.

Example

let options = PgConnectOptions::new()
    .username("root")
    .password("safe-and-secure");

pub fn database(self, database: &str) -> PgConnectOptions

Sets the database name. Defaults to be the same as the user name.

Example

let options = PgConnectOptions::new()
    .database("postgres");

pub fn ssl_mode(self, mode: PgSslMode) -> PgConnectOptions

Sets whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.

By default, the SSL mode is Prefer, and the client will first attempt an SSL connection but fallback to a non-SSL connection on failure.

Ignored for Unix domain socket communication.

Example

let options = PgConnectOptions::new()
    .ssl_mode(PgSslMode::Require);

pub fn ssl_root_cert(self, cert: impl AsRef<Path>) -> PgConnectOptions

Sets the name of a file containing SSL certificate authority (CA) certificate(s). If the file exists, the server’s certificate will be verified to be signed by one of these authorities.

Example

let options = PgConnectOptions::new()
    // Providing a CA certificate with less than VerifyCa is pointless
    .ssl_mode(PgSslMode::VerifyCa)
    .ssl_root_cert("./ca-certificate.crt");

pub fn ssl_client_cert(self, cert: impl AsRef<Path>) -> PgConnectOptions

Sets the name of a file containing SSL client certificate.

Example

let options = PgConnectOptions::new()
    // Providing a CA certificate with less than VerifyCa is pointless
    .ssl_mode(PgSslMode::VerifyCa)
    .ssl_client_cert("./client.crt");

pub fn ssl_client_cert_from_pem( self, cert: impl AsRef<[u8]>, ) -> PgConnectOptions

Sets the SSL client certificate as a PEM-encoded byte slice.

This should be an ASCII-encoded blob that starts with -----BEGIN CERTIFICATE-----.

Example

Note: embedding SSL certificates and keys in the binary is not advised. This is for illustration purposes only.

const CERT: &[u8] = b"\
-----BEGIN CERTIFICATE-----
<Certificate data here.>
-----END CERTIFICATE-----";
    
let options = PgConnectOptions::new()
    // Providing a CA certificate with less than VerifyCa is pointless
    .ssl_mode(PgSslMode::VerifyCa)
    .ssl_client_cert_from_pem(CERT);

pub fn ssl_client_key(self, key: impl AsRef<Path>) -> PgConnectOptions

Sets the name of a file containing SSL client key.

Example

let options = PgConnectOptions::new()
    // Providing a CA certificate with less than VerifyCa is pointless
    .ssl_mode(PgSslMode::VerifyCa)
    .ssl_client_key("./client.key");

pub fn ssl_client_key_from_pem(self, key: impl AsRef<[u8]>) -> PgConnectOptions

Sets the SSL client key as a PEM-encoded byte slice.

This should be an ASCII-encoded blob that starts with -----BEGIN PRIVATE KEY-----.

Example

Note: embedding SSL certificates and keys in the binary is not advised. This is for illustration purposes only.

const KEY: &[u8] = b"\
-----BEGIN PRIVATE KEY-----
<Private key data here.>
-----END PRIVATE KEY-----";

let options = PgConnectOptions::new()
    // Providing a CA certificate with less than VerifyCa is pointless
    .ssl_mode(PgSslMode::VerifyCa)
    .ssl_client_key_from_pem(KEY);

pub fn ssl_root_cert_from_pem( self, pem_certificate: Vec<u8>, ) -> PgConnectOptions

Sets PEM encoded trusted SSL Certificate Authorities (CA).

Example

let options = PgConnectOptions::new()
    // Providing a CA certificate with less than VerifyCa is pointless
    .ssl_mode(PgSslMode::VerifyCa)
    .ssl_root_cert_from_pem(vec![]);

pub fn statement_cache_capacity(self, capacity: usize) -> PgConnectOptions

Sets the capacity of the connection’s statement cache in a number of stored distinct statements. Caching is handled using LRU, meaning when the amount of queries hits the defined limit, the oldest statement will get dropped.

The default cache capacity is 100 statements.

pub fn application_name(self, application_name: &str) -> PgConnectOptions

Sets the application name. Defaults to None

Example

let options = PgConnectOptions::new()
    .application_name("my-app");

pub fn extra_float_digits( self, extra_float_digits: impl Into<Option<i8>>, ) -> PgConnectOptions

Sets or removes the extra_float_digits connection option.

This changes the default precision of floating-point values returned in text mode (when not using prepared statements such as calling methods of Executor directly).

Historically, Postgres would by default round floating-point values to 6 and 15 digits for float4/REAL (f32) and float8/DOUBLE (f64), respectively, which would mean that the returned value may not be exactly the same as its representation in Postgres.

The nominal range for this value is -15 to 3, where negative values for this option cause floating-points to be rounded to that many fewer digits than normal (-1 causes float4 to be rounded to 5 digits instead of six, or 14 instead of 15 for float8), positive values cause Postgres to emit that many extra digits of precision over default (or simply use maximum precision in Postgres 12 and later), and 0 means keep the default behavior (or the “old” behavior described above as of Postgres 12).

SQLx sets this value to 3 by default, which tells Postgres to return floating-point values at their maximum precision in the hope that the parsed value will be identical to its counterpart in Postgres. This is also the default in Postgres 12 and later anyway.

However, older versions of Postgres and alternative implementations that talk the Postgres protocol may not support this option, or the full range of values.

If you get an error like “unknown option extra_float_digits” when connecting, try setting this to None or consult the manual of your database for the allowed range of values.

For more information, see:

• Postgres manual, 20.11.2: Client Connection Defaults; Locale and Formatting
• Postgres manual, 8.1.3: Numeric Types; Floating-point Types

Examples

let mut options = PgConnectOptions::new()
    // for Redshift and Postgres 10
    .extra_float_digits(2);

let mut options = PgConnectOptions::new()
    // don't send the option at all (Postgres 9 and older)
    .extra_float_digits(None);

pub fn options<K, V, I>(self, options: I) -> PgConnectOptions

where K: Display, V: Display, I: IntoIterator<Item = (K, V)>,

Set additional startup options for the connection as a list of key-value pairs.

Example

let options = PgConnectOptions::new()
    .options([("geqo", "off"), ("statement_timeout", "5min")]);

impl PgConnectOptions

pub fn get_host(&self) -> &str

Get the current host.

Example

let options = PgConnectOptions::new()
    .host("127.0.0.1");
assert_eq!(options.get_host(), "127.0.0.1");

pub fn get_port(&self) -> u16

Get the server’s port.

Example

let options = PgConnectOptions::new()
    .port(6543);
assert_eq!(options.get_port(), 6543);

pub fn get_socket(&self) -> Option<&PathBuf>

Get the socket path.

Example

let options = PgConnectOptions::new()
    .socket("/tmp");
assert!(options.get_socket().is_some());

pub fn get_username(&self) -> &str

Get the server’s port.

Example

let options = PgConnectOptions::new()
    .username("foo");
assert_eq!(options.get_username(), "foo");

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

Get the current database name.

Example

let options = PgConnectOptions::new()
    .database("postgres");
assert!(options.get_database().is_some());

pub fn get_ssl_mode(&self) -> PgSslMode

Get the SSL mode.

Example

let options = PgConnectOptions::new();
assert!(matches!(options.get_ssl_mode(), PgSslMode::Prefer));

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

Get the application name.

Example

let options = PgConnectOptions::new()
    .application_name("service");
assert!(options.get_application_name().is_some());

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

Get the options.

Example

let options = PgConnectOptions::new()
    .options([("foo", "bar")]);
assert!(options.get_options().is_some());

Trait Implementations

impl Clone for PgConnectOptions

fn clone(&self) -> PgConnectOptions

Returns a copy of the value.

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

Performs copy-assignment from source.

impl ConnectOptions for PgConnectOptions

type Connection = PgConnection

fn from_url(url: &Url) -> Result<PgConnectOptions, Error>

Parse the ConnectOptions from a URL.

fn to_url_lossy(&self) -> Url

Get a connection URL that may be used to connect to the same database as this ConnectOptions.

fn connect( &self, ) -> Pin<Box<dyn Future<Output = Result<<PgConnectOptions as ConnectOptions>::Connection, Error>> + Send + '_>>

where <PgConnectOptions as ConnectOptions>::Connection: Sized,

Establish a new database connection with the options specified by self.

fn log_statements(self, level: LevelFilter) -> PgConnectOptions

Log executed statements with the specified level

fn log_slow_statements( self, level: LevelFilter, duration: Duration, ) -> PgConnectOptions

Log executed statements with a duration above the specified duration at the specified level.

fn disable_statement_logging(self) -> Self

Entirely disables statement logging (both slow and regular).

impl Debug for PgConnectOptions

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

Formats the value using the given formatter.

impl Default for PgConnectOptions

fn default() -> PgConnectOptions

Returns the “default value” for a type.

impl FromStr for PgConnectOptions

type Err = Error

The associated error which can be returned from parsing.

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

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

impl<'a> TryFrom<&'a AnyConnectOptions> for PgConnectOptions

type Error = Error

The type returned in the event of a conversion error.

fn try_from( value: &'a AnyConnectOptions, ) -> Result<PgConnectOptions, <PgConnectOptions as TryFrom<&'a AnyConnectOptions>>::Error>

Performs the conversion.