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| {
        Box::pin(async move {
            if meta.idle_for >= idle {
                conn.ping().await?;
            }
            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) -> BoxFuture<'static, Result<(), DbErr>> + Send + Sync + 'static,

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

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

where F: Fn(MySqlConnectOptions) -> MySqlConnectOptions + Send + Sync + 'static,

Available on crate feature sqlx-mysql only.

Apply a function to modify the underlying MySqlConnectOptions before creating the connection pool.

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

where F: Fn(PoolOptions<MySql>) -> PoolOptions<MySql> + Send + Sync + 'static,

Available on crate feature sqlx-mysql only.

Apply a function to modify the underlying sqlx::pool::PoolOptions<sqlx::MySql> before creating the connection pool.

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

where F: Fn(PgConnectOptions) -> PgConnectOptions + Send + Sync + 'static,

Available on crate feature sqlx-postgres only.

Apply a function to modify the underlying PgConnectOptions before creating the connection pool.

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

where F: Fn(PoolOptions<Postgres>) -> PoolOptions<Postgres> + Send + Sync + 'static,

Available on crate feature sqlx-postgres only.

Apply a function to modify the underlying sqlx::pool::PoolOptions<sqlx::Postgres> before creating the connection pool.

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

where F: Fn(SqliteConnectOptions) -> SqliteConnectOptions + Send + Sync + 'static,

Available on crate feature sqlx-sqlite only.

Apply a function to modify the underlying SqliteConnectOptions before creating the connection pool.

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

where F: Fn(PoolOptions<Sqlite>) -> PoolOptions<Sqlite> + Send + Sync + 'static,

Available on crate feature sqlx-sqlite only.

Apply a function to modify the underlying sqlx::pool::PoolOptions<sqlx::Sqlite> before creating the connection pool.

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

where F: for<'c> Fn(&'c mut MySqlConnection, PoolConnectionMetadata) -> BoxFuture<'c, Result<bool, Error>> + Send + Sync + 'static,

Available on crate feature sqlx-mysql only.

Set a before_acquire callback run on an idle pooled MySQL connection before it is handed out.

Return Ok(true) to use the connection, or Ok(false)/Err(_) to discard it and let the pool try another (opening a fresh one if needed). Composes after the idle-ping installed by test_before_acquire_if_idle_for — that runs first, then this callback.

Applies only to pools built through Database::connect, not to pools adopted via SqlxMySqlConnector::from_sqlx_mysql_pool.

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

where F: for<'c> Fn(&'c mut PgConnection, PoolConnectionMetadata) -> BoxFuture<'c, Result<bool, Error>> + Send + Sync + 'static,

Available on crate feature sqlx-postgres only.

Set a before_acquire callback run on an idle pooled PostgreSQL connection before it is handed out.

Return Ok(true) to use the connection, or Ok(false)/Err(_) to discard it and let the pool try another (opening a fresh one if needed). Composes after the idle-ping installed by test_before_acquire_if_idle_for — that runs first, then this callback.

Applies only to pools built through Database::connect, not to pools adopted via SqlxPostgresConnector::from_sqlx_postgres_pool.

Example

let mut opt = ConnectOptions::new("postgres://localhost/db");
opt.map_sqlx_postgres_before_acquire(|_conn, meta| {
    Box::pin(async move {
        // Discard (and transparently replace) connections older than 10 minutes,
        // rather than pinging on every acquire.
        Ok(meta.age < Duration::from_secs(600))
    })
});

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

where F: for<'c> Fn(&'c mut SqliteConnection, PoolConnectionMetadata) -> BoxFuture<'c, Result<bool, Error>> + Send + Sync + 'static,

Available on crate feature sqlx-sqlite only.

Set a before_acquire callback run on an idle pooled SQLite connection before it is handed out.

Return Ok(true) to use the connection, or Ok(false)/Err(_) to discard it and let the pool try another (opening a fresh one if needed). Composes after the idle-ping installed by test_before_acquire_if_idle_for — that runs first, then this callback.

Applies only to pools built through Database::connect, not to pools adopted via SqlxSqliteConnector::from_sqlx_sqlite_pool.

impl ConnectOptions

pub fn sqlx_pool_options<DB>(self) -> PoolOptions<DB>

where DB: Database,

Available on crate feature sqlx-dep only.

Convert ConnectOptions into sqlx::pool::PoolOptions

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.