pub struct PgConnectOptions { /* private fields */ }
Expand description

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&...]

Parameters

ParameterDefaultDescription
sslmodepreferDetermines whether or with what priority a secure SSL TCP/IP connection will be negotiated. See PgSslMode.
sslrootcertNoneSets the name of a file containing a list of trusted SSL Certificate Authorities.
statement-cache-capacity100The maximum number of prepared statements stored in the cache. Set to 0 to disable.
hostNonePath to the directory containing a PostgreSQL unix domain socket, which will be used instead of TCP if set.
hostaddrNoneSame as host, but only accepts IP addresses.
application-nameNoneThe name will be displayed in the pg_stat_activity view and included in CSV log entries.
userresult of whoamiPostgreSQL user name to connect as.
passwordNonePassword to be used if the server demands password authentication.
port5432Port number to connect to at the server host, or socket file name extension for Unix-domain connections.
dbnameNoneThe database name.
optionsNoneThe runtime parameters to send to the server at connection start.

The URL scheme designator can be either postgresql:// or postgres://. Each of the URL 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

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

Implementations§

source§

impl PgConnectOptions

source

pub fn new() -> Self

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();
source

pub fn new_without_pgpass() -> Self

source

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

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");
source

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

Sets the port to connect to at the server host.

The default port for PostgreSQL is 5432.

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

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

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.

source

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

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");
source

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

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

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

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

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

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

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());
source

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

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);
source

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

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");
source

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

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![]);
source

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

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.

source

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

Sets the application name. Defaults to None

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

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

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:

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);
source

pub fn options<K, V, I>(self, options: I) -> Selfwhere 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§

source§

impl Clone for PgConnectOptions

source§

fn clone(&self) -> PgConnectOptions

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 ConnectOptions for PgConnectOptions

§

type Connection = PgConnection

source§

fn connect(&self) -> BoxFuture<'_, Result<Self::Connection, Error>>where Self::Connection: Sized,

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

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

Log executed statements with the specified level
source§

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

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

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

Entirely disables statement logging (both slow and regular).
source§

impl Debug for PgConnectOptions

source§

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

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

impl Default for PgConnectOptions

source§

fn default() -> Self

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

impl From<PgConnectOptions> for AnyConnectOptions

source§

fn from(options: PgConnectOptions) -> Self

Converts to this type from the input type.
source§

impl FromStr for PgConnectOptions

§

type Err = Error

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

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

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

impl TryFrom<AnyConnectOptions> for PgConnectOptions

§

type Error = Error

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

fn try_from(value: AnyConnectOptions) -> Result<Self, Self::Error>

Performs the conversion.

Auto Trait Implementations§

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

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

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

const: unstable · source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

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

const: unstable · 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<T> for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for Twhere 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 Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

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

Performs the conversion.
source§

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

§

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

The type returned in the event of a conversion error.
const: unstable · source§

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

Performs the conversion.
§

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

§

fn vzip(self) -> V