Struct sqlx::postgres::PgConnectOptions

pub struct PgConnectOptions { /* fields omitted */ }

This is supported 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 URI, as described by libpq.

The general form for a connection URI is:

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

Parameters

Parameter	Default	Description
sslmode	prefer	Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated. See PgSslMode.
sslrootcert	None	Sets the name of a file containing a list of trusted SSL Certificate Authorities.
statement-cache-capacity	100	The maximum number of prepared statements stored in the cache. Set to 0 to disable.
host	None	Path to the directory containing a PostgreSQL unix domain socket, which will be used instead of TCP if set.
hostaddr	None	Same as host, but only accepts IP addresses.
application-name	None	The name will be displayed in the pg_stat_activity view and included in CSV log entries.
user	result of whoami	PostgreSQL user name to connect as.
password	None	Password to be used if the server demands password authentication.
port	5432	Port number to connect to at the server host, or socket file name extension for Unix-domain connections.
dbname	None	The database name.
options	None	The runtime parameters to send to the server at connection start.

The URI scheme designator can be either postgresql:// or postgres://. Each of the URI parts is optional.

postgresql://
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/mydb
postgresql://user@localhost
postgresql://user:secret@localhost
postgresql://localhost?dbname=mydb&user=postgres&password=postgres

Example

// URI 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?;

Implementations

impl PgConnectOptions

pub fn new() -> PgConnectOptions

Creates a new, default set of options ready for configuration.

By default, this reads the following environment variables and sets their equivalent options.

• PGHOST
• PGPORT
• PGUSER
• PGPASSWORD
• PGDATABASE
• PGSSLROOTCERT
• PGSSLMODE
• PGAPPNAME

Example

let options = PgConnectOptions::new();

pub fn new_without_pgpass() -> PgConnectOptions

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_root_cert_from_pem(
    self,
    pem_certificate: Vec<u8, Global>
) -> 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 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")]);

Trait Implementations

impl Clone for PgConnectOptions

pub 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

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

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

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

Log executed statements with the specified level

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

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

fn disable_statement_logging(&mut self) -> &mut Self

Entirely disables statement logging (both slow and regular).

impl Debug for PgConnectOptions

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

Formats the value using the given formatter.

impl Default for PgConnectOptions

pub fn default() -> PgConnectOptions

Returns the “default value” for a type.

impl From<PgConnectOptions> for AnyConnectOptions

pub fn from(options: PgConnectOptions) -> AnyConnectOptions

Performs the conversion.

impl FromStr for PgConnectOptions

type Err = Error

The associated error which can be returned from parsing.

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

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