Trait Connection 

pub trait Connection: Send + Sync {
    type Tx<'conn>: TransactionOps
       where Self: 'conn;

    // Required methods
    fn query(
        &self,
        cx: &Cx,
        sql: &str,
        params: &[Value],
    ) -> impl Future<Output = Outcome<Vec<Row>, Error>> + Send;
    fn query_one(
        &self,
        cx: &Cx,
        sql: &str,
        params: &[Value],
    ) -> impl Future<Output = Outcome<Option<Row>, Error>> + Send;
    fn execute(
        &self,
        cx: &Cx,
        sql: &str,
        params: &[Value],
    ) -> impl Future<Output = Outcome<u64, Error>> + Send;
    fn insert(
        &self,
        cx: &Cx,
        sql: &str,
        params: &[Value],
    ) -> impl Future<Output = Outcome<i64, Error>> + Send;
    fn batch(
        &self,
        cx: &Cx,
        statements: &[(String, Vec<Value>)],
    ) -> impl Future<Output = Outcome<Vec<u64>, Error>> + Send;
    fn begin(
        &self,
        cx: &Cx,
    ) -> impl Future<Output = Outcome<Self::Tx<'_>, Error>> + Send;
    fn begin_with(
        &self,
        cx: &Cx,
        isolation: IsolationLevel,
    ) -> impl Future<Output = Outcome<Self::Tx<'_>, Error>> + Send;
    fn prepare(
        &self,
        cx: &Cx,
        sql: &str,
    ) -> impl Future<Output = Outcome<PreparedStatement, Error>> + Send;
    fn query_prepared(
        &self,
        cx: &Cx,
        stmt: &PreparedStatement,
        params: &[Value],
    ) -> impl Future<Output = Outcome<Vec<Row>, Error>> + Send;
    fn execute_prepared(
        &self,
        cx: &Cx,
        stmt: &PreparedStatement,
        params: &[Value],
    ) -> impl Future<Output = Outcome<u64, Error>> + Send;
    fn ping(&self, cx: &Cx) -> impl Future<Output = Outcome<(), Error>> + Send;
    fn close(self, cx: &Cx) -> impl Future<Output = Result<()>> + Send;

    // Provided methods
    fn dialect(&self) -> Dialect { ... }
    fn is_valid(&self, cx: &Cx) -> impl Future<Output = bool> + Send { ... }
    fn close_for_pool(self, cx: &Cx) -> impl Future<Output = Result<()>> + Send
       where Self: Sized { ... }
}

Required Associated Types

type Tx<'conn>: TransactionOps where Self: 'conn

The transaction type returned by this connection.

Required Methods

fn query( &self, cx: &Cx, sql: &str, params: &[Value], ) -> impl Future<Output = Outcome<Vec<Row>, Error>> + Send

Execute a query and return all rows.

fn query_one( &self, cx: &Cx, sql: &str, params: &[Value], ) -> impl Future<Output = Outcome<Option<Row>, Error>> + Send

Execute a query and return the first row, if any.

fn execute( &self, cx: &Cx, sql: &str, params: &[Value], ) -> impl Future<Output = Outcome<u64, Error>> + Send

Execute a statement (INSERT, UPDATE, DELETE) and return rows affected.

fn insert( &self, cx: &Cx, sql: &str, params: &[Value], ) -> impl Future<Output = Outcome<i64, Error>> + Send

Execute an INSERT and return the last inserted ID.

For PostgreSQL, this typically uses RETURNING to get the inserted ID. The exact behavior depends on the driver implementation.

fn batch( &self, cx: &Cx, statements: &[(String, Vec<Value>)], ) -> impl Future<Output = Outcome<Vec<u64>, Error>> + Send

Execute multiple statements in a batch.

Returns the number of rows affected by each statement. The statements are executed sequentially but may be optimized by the driver for better performance.

fn begin( &self, cx: &Cx, ) -> impl Future<Output = Outcome<Self::Tx<'_>, Error>> + Send

Begin a transaction with default isolation level (ReadCommitted).

fn begin_with( &self, cx: &Cx, isolation: IsolationLevel, ) -> impl Future<Output = Outcome<Self::Tx<'_>, Error>> + Send

Begin a transaction with a specific isolation level.

fn prepare( &self, cx: &Cx, sql: &str, ) -> impl Future<Output = Outcome<PreparedStatement, Error>> + Send

Prepare a statement for repeated execution.

Prepared statements are cached by the driver and can be executed multiple times with different parameters efficiently.

fn query_prepared( &self, cx: &Cx, stmt: &PreparedStatement, params: &[Value], ) -> impl Future<Output = Outcome<Vec<Row>, Error>> + Send

Execute a prepared statement and return all rows.

fn execute_prepared( &self, cx: &Cx, stmt: &PreparedStatement, params: &[Value], ) -> impl Future<Output = Outcome<u64, Error>> + Send

Execute a prepared statement (INSERT, UPDATE, DELETE) and return rows affected.

fn ping(&self, cx: &Cx) -> impl Future<Output = Outcome<(), Error>> + Send

Check if the connection is still valid by sending a ping.

fn close(self, cx: &Cx) -> impl Future<Output = Result<()>> + Send

Close the connection gracefully.

Provided Methods

fn dialect(&self) -> Dialect

Get the SQL dialect for this connection.

This is used by query builders to generate dialect-specific SQL. Defaults to Postgres for backwards compatibility.

fn is_valid(&self, cx: &Cx) -> impl Future<Output = bool> + Send

Check if the connection is still valid (alias for ping that returns bool).

fn close_for_pool(self, cx: &Cx) -> impl Future<Output = Result<()>> + Send

where Self: Sized,

Close the connection as part of pool retirement.

The pool routes every teardown (shutdown, idle eviction, max-lifetime expiry, and failed checkout validation) through this method exactly once after removing the connection from pool state. It is never awaited while the pool’s internal mutex is held. Returning a healthy connection to the idle queue does not call this method.

The default simply delegates to Connection::close, so callers that close a connection they own directly see no behavioral change. Drivers may override this with a cheaper teardown path — for example skipping a close-time WAL checkpoint to avoid contention when many pooled connections retire at once — provided all committed data remains durable and recoverable by the next open.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors