Struct ConnectOptions 

pub struct ConnectOptions { /* private fields */ }

Configuration for opening a DatabaseConnection: connection URL, pool sizing, timeouts, logging, and backend-specific options.

Construct with ConnectOptions::new (or directly from a URL &str), then chain the setter methods before passing to Database::connect.

Implementations

impl ConnectOptions

pub fn new<T>(url: T) -> Self

where T: Into<String>,

Create new ConnectOptions for a Database by passing in a URI string

pub fn get_url(&self) -> &str

Get the database URL of the pool

pub fn max_connections(&mut self, value: u32) -> &mut Self

Set the maximum number of connections of the pool

pub fn get_max_connections(&self) -> Option<u32>

Get the maximum number of connections of the pool, if set

pub fn min_connections(&mut self, value: u32) -> &mut Self

Set the minimum number of connections of the pool

pub fn get_min_connections(&self) -> Option<u32>

Get the minimum number of connections of the pool, if set

pub fn connect_timeout(&mut self, value: Duration) -> &mut Self

Set the timeout duration when acquiring a connection

pub fn get_connect_timeout(&self) -> Option<Duration>

Get the timeout duration when acquiring a connection, if set

pub fn idle_timeout<T>(&mut self, value: T) -> &mut Self

where T: Into<Option<Duration>>,

Set the idle duration before closing a connection.

pub fn get_idle_timeout(&self) -> Option<Option<Duration>>

Get the idle duration before closing a connection, if set

pub fn acquire_timeout(&mut self, value: Duration) -> &mut Self

Set the maximum amount of time to spend waiting for acquiring a connection

pub fn get_acquire_timeout(&self) -> Option<Duration>

Get the maximum amount of time to spend waiting for acquiring a connection

pub fn max_lifetime<T>(&mut self, lifetime: T) -> &mut Self

where T: Into<Option<Duration>>,

Set the maximum lifetime of individual connections.

pub fn get_max_lifetime(&self) -> Option<Option<Duration>>

Get the maximum lifetime of individual connections, if set

pub fn sqlx_logging(&mut self, value: bool) -> &mut Self

Enable SQLx statement logging (default true)

pub fn get_sqlx_logging(&self) -> bool

Get whether SQLx statement logging is enabled

pub fn record_stmt_in_spans(&mut self, value: bool) -> &mut Self

Enable recording db.statement in tracing spans (default true).

pub fn get_record_stmt_in_spans(&self) -> bool

Get whether db.statement recording in tracing spans is enabled.

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

Set SQLx statement logging level (default INFO). (ignored if sqlx_logging is false)

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

Set SQLx slow statements logging level and duration threshold (default LevelFilter::Off). (ignored if sqlx_logging is false)

pub fn get_sqlx_logging_level(&self) -> LevelFilter

Get the level of SQLx statement logging

pub fn get_sqlx_slow_statements_logging_settings( &self, ) -> (LevelFilter, Duration)

Get the SQLx slow statements logging settings

pub fn sqlcipher_key<T>(&mut self, value: T) -> &mut Self

where T: Into<Cow<'static, str>>,

set key for sqlcipher

pub fn set_schema_search_path<T>(&mut self, schema_search_path: T) -> &mut Self

where T: Into<String>,

Set schema search path (PostgreSQL only)

pub fn set_application_name<T>(&mut self, application_name: T) -> &mut Self

where T: Into<String>,

Set application name (PostgreSQL only)

pub fn statement_timeout(&mut self, value: Duration) -> &mut Self

Set the statement timeout (PostgreSQL only).

This sets the PostgreSQL statement_timeout parameter via the connection options, causing the server to abort any statement that exceeds the specified duration. The timeout is applied at connection time and does not require an extra roundtrip.

Has no effect on MySQL or SQLite connections.

pub fn get_statement_timeout(&self) -> Option<Duration>

Get the statement timeout, if set

pub fn test_before_acquire(&mut self, value: bool) -> &mut Self

If true, the connection will be pinged upon acquiring from the pool (default true).

See test_before_acquire_if_idle_for for the cheaper “only ping stale connections” variant.

pub fn get_test_before_acquire(&self) -> bool

Get whether a pooled connection is pinged on every acquire (default true).

pub fn test_before_acquire_if_idle_for(&mut self, idle: Duration) -> &mut Self

Ping a pooled connection before handing it out, but only once it has been idle for at least idle.

test_before_acquire pings on every acquire, which adds a round-trip to each checkout. This shorthand instead pings only connections that have been idle long enough to plausibly have been dropped by the server, a proxy, or a firewall — the common failure mode — while letting hot connections through untouched.

Calling this sets test_before_acquire to false (SQLx runs the per-acquire ping and this hook, so leaving it enabled would ping on every acquire regardless and defeat the threshold).

It composes with a per-backend map_sqlx_postgres_before_acquire callback (and its MySQL / SQLite counterparts): the idle-ping runs first, then your callback.

Expands to

With no per-backend callback set, this is exactly the following configuration on the underlying [sqlx::pool::PoolOptions]:

pool_options
    .test_before_acquire(false)
    .before_acquire(move |conn, meta| {
        ({
            if meta.idle_for >= idle {
                conn.ping()?;
            }
            Ok(true)
        })
    })

Applies only to pools built through Database::connect. Pools adopted via SqlxPostgresConnector::from_sqlx_postgres_pool (and the MySQL / SQLite equivalents) bypass ConnectOptions entirely — configure before_acquire on your own [sqlx::pool::PoolOptions] in that case.

Example

let mut opt = ConnectOptions::new("postgres://localhost/db");
opt.test_before_acquire_if_idle_for(Duration::from_secs(30));
assert_eq!(opt.get_test_before_acquire(), false);

pub fn get_test_before_acquire_if_idle_for(&self) -> Option<Duration>

Get the idle threshold set by test_before_acquire_if_idle_for, if any.

pub fn connect_lazy(&mut self, value: bool) -> &mut Self

If set to true, the db connection pool will be created using SQLx’s connect_lazy method.

pub fn get_connect_lazy(&self) -> bool

Get whether DB connections will be established when the pool is created or only as needed.

pub fn after_connect<F>(&mut self, f: F) -> &mut Self

where F: Fn(DatabaseConnection) -> Result<(), DbErr> + 'static,

Set a callback function that will be called after a new connection is established.

Trait Implementations

impl Clone for ConnectOptions

fn clone(&self) -> ConnectOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ConnectOptions

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

Formats the value using the given formatter.

impl<T> From<T> for ConnectOptions

where T: Into<String>,

fn from(s: T) -> ConnectOptions

Converts to this type from the input type.