Skip to main content

PgConfig

Struct PgConfig 

Source
#[non_exhaustive]
pub struct PgConfig {
Show 17 fields pub url: String, pub host: String, pub port: u16, pub database: String, pub user: String, pub password: Option<String>, pub ssl_mode: SslMode, pub ssl_root_cert: Option<PathBuf>, pub connect_timeout: Duration, pub statement_timeout: Option<Duration>, pub application_name: Option<String>, pub keepalives: bool, pub keepalives_idle: Option<Duration>, pub keepalives_interval: Option<Duration>, pub keepalives_retries: Option<u32>, pub tcp_user_timeout: Option<Duration>, pub options: Vec<(String, String)>,
}
Expand description

PostgreSQL connection configuration.

Debug output redacts password and any password in url.

Fields (Non-exhaustive)§

This struct is marked as non-exhaustive
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§url: String

Database URL.

§host: String

Host (extracted from URL or explicit).

§port: u16

Port (default: 5432).

§database: String

Database name.

§user: String

Username.

§password: Option<String>

Password.

§ssl_mode: SslMode

SSL mode.

With the default tls cargo feature, TLS connections are established via rustls with certificates verified against the Mozilla root store (chain + hostname). Without the feature, any TLS-requiring mode fails at pool build time with a clear error — it is never silently downgraded to plaintext.

§ssl_root_cert: Option<PathBuf>

Path to a PEM file of root certificates to verify the server against, from the libpq-compatible sslrootcert URL parameter.

When set, these certificates replace the Mozilla root store rather than adding to it, matching libpq: a pool talks to one server, and “trust exactly this bundle” is both the stricter and the more predictable reading.

The case this exists for is a server whose CA is deliberately not publicly trusted — Amazon RDS being the common one, since its rds-ca-* authorities are Amazon-operated and absent from the Mozilla store, so the default configuration cannot verify them at all.

§connect_timeout: Duration

Connection timeout.

§statement_timeout: Option<Duration>

Statement timeout.

§application_name: Option<String>

Application name (shown in pg_stat_activity).

§keepalives: bool

Whether TCP keepalives are enabled on the client socket (default: true, the tokio-postgres default). From the libpq-compatible keepalives URL parameter (0 disables, any other integer enables).

§keepalives_idle: Option<Duration>

Idle time before the first TCP keepalive probe is sent. None keeps the driver default (2 hours). From the keepalives_idle URL parameter (seconds; 0 keeps the default, as in libpq).

Together with keepalives_interval and keepalives_retries this bounds how long an idle connection whose peer vanished (failover, network black-hole) goes undetected.

§keepalives_interval: Option<Duration>

Interval between unanswered TCP keepalive probes. None keeps the OS default. From the keepalives_interval URL parameter (seconds; 0 keeps the default).

§keepalives_retries: Option<u32>

Number of unanswered TCP keepalive probes before the connection is dropped. None keeps the OS default. From the libpq keepalives_count URL parameter (also accepted as tokio-postgres’s keepalives_retries; 0 keeps the default).

§tcp_user_timeout: Option<Duration>

TCP_USER_TIMEOUT: how long transmitted data may stay unacknowledged before the OS closes the connection (Linux only; ignored elsewhere). None keeps the OS default (~15 minutes of retransmissions on Linux). From the tcp_user_timeout URL parameter (milliseconds; 0 keeps the default, as in libpq).

This bounds how long a query sent on a connection whose peer vanished hangs, which keepalives alone do not.

§options: Vec<(String, String)>

Additional options.

Implementations§

Source§

impl PgConfig

Source

pub fn from_url(url: impl Into<String>) -> PgResult<Self>

Create a new configuration from a database URL.

The user name, password and database name are percent-decoded, as libpq does: write reserved characters in them (@, /, ?, #, :) percent-encoded. A URL whose password evidently contains them unencoded (an @ after the host) is rejected with a configuration error rather than parsed into the wrong host, port or database.

As with libpq, user and password query parameters set the credentials (overriding the user info). The libpq client-side TCP parameters keepalives, keepalives_idle (seconds), keepalives_interval (seconds), keepalives_count (alias keepalives_retries) and tcp_user_timeout (milliseconds) configure the client socket; an invalid value is a configuration error. Other unrecognised parameters become options (server GUCs).

Source

pub fn builder() -> PgConfigBuilder

Create a builder for configuration.

Source

pub fn to_pg_config(&self) -> Config

Convert to tokio-postgres config.

Applies everything tokio_postgres::Config can express without a TLS connector: host/port/dbname/user/password, application_name, connect_timeout, the driver’s tokio_postgres::config::SslMode, the client TCP settings (keepalives, keepalives_idle, keepalives_interval, keepalives_retries, tcp_user_timeout; unset or zero values keep the driver/OS defaults), plus statement_timeout and any extra options (passed via the libpq-style options startup parameter as space-separated -c key=value pairs).

Option pairs whose key is not a valid GUC name, or whose value contains whitespace / \ / ', are dropped with a warning: percent-decoded values could otherwise smuggle extra -c assignments into the space-joined string.

Require/VerifyCa/VerifyFull all map to the driver’s SslMode::Require; the pool supplies the rustls connector (with webpki certificate verification) that makes the mode satisfiable.

Trait Implementations§

Source§

impl Clone for PgConfig

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for PgConfig

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

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§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

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

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

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

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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

Source§

type Output = T

Should always be Self
Source§

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

Source§

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

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

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

Source§

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<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

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

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

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