Trait Connection 

pub trait Connection: Send {
    type Database: Database<Connection = Self>;
    type Options: ConnectOptions<Connection = Self>;

    // Required methods
    fn close(self) -> impl Future<Output = Result<(), Error>> + Send + 'static;
    fn ping(&mut self) -> impl Future<Output = Result<(), Error>> + Send + '_;
    fn begin(
        &mut self,
    ) -> impl Future<Output = Result<Transaction<'_, Self::Database>, Error>> + Send + '_;
    fn shrink_buffers(&mut self);

    // Provided methods
    fn begin_with(
        &mut self,
        statement: impl SqlSafeStr,
    ) -> impl Future<Output = Result<Transaction<'_, Self::Database>, Error>> + Send + '_
       where Self: Sized { ... }
    fn is_in_transaction(&self) -> bool { ... }
    fn transaction<'a, F, R, E>(
        &'a mut self,
        callback: F,
    ) -> impl Future<Output = Result<R, E>> + Send + 'a
       where for<'c> F: FnOnce(&'c mut Transaction<'_, Self::Database>) -> BoxFuture<'c, Result<R, E>> + 'a + Send + Sync,
             Self: Sized,
             R: Send,
             E: From<Error> + Send { ... }
    fn cached_statements_size(&self) -> usize
       where Self::Database: HasStatementCache { ... }
    fn clear_cached_statements(
        &mut self,
    ) -> impl Future<Output = Result<(), Error>> + Send + '_
       where Self::Database: HasStatementCache { ... }
    fn connect(
        url: &str,
    ) -> impl Future<Output = Result<Self, Error>> + Send + 'static
       where Self: Sized { ... }
    fn connect_with(
        options: &Self::Options,
    ) -> impl Future<Output = Result<Self, Error>> + Send + '_
       where Self: Sized { ... }
}

Represents a single database connection.

Required Associated Types

type Database: Database<Connection = Self>

type Options: ConnectOptions<Connection = Self>

Required Methods

fn close(self) -> impl Future<Output = Result<(), Error>> + Send + 'static

Explicitly close this database connection.

This notifies the database server that the connection is closing so that it can free up any server-side resources in use.

While connections can simply be dropped to clean up local resources, the Drop handler itself cannot notify the server that the connection is being closed because that may require I/O to send a termination message. That can result in a delay before the server learns that the connection is gone, usually from a TCP keepalive timeout.

Creating and dropping many connections in short order without calling .close() may lead to errors from the database server because those senescent connections will still count against any connection limit or quota that is configured.

Therefore it is recommended to call .close() on a connection when you are done using it and to .await the result to ensure the termination message is sent.

fn ping(&mut self) -> impl Future<Output = Result<(), Error>> + Send + '_

Checks if a connection to the database is still valid.

fn begin( &mut self, ) -> impl Future<Output = Result<Transaction<'_, Self::Database>, Error>> + Send + '_

Begin a new transaction or establish a savepoint within the active transaction.

Returns a Transaction for controlling and tracking the new transaction.

fn shrink_buffers(&mut self)

Restore any buffers in the connection to their default capacity, if possible.

Sending a large query or receiving a resultset with many columns can cause the connection to allocate additional buffer space to fit the data which is retained afterwards in case it’s needed again. This can give the outward appearance of a memory leak, but is in fact the intended behavior.

Calling this method tells the connection to release that excess memory if it can, though be aware that calling this too often can cause unnecessary thrashing or fragmentation in the global allocator. If there’s still data in the connection buffers (unlikely if the last query was run to completion) then it may need to be moved to allow the buffers to shrink.

Provided Methods

fn begin_with( &mut self, statement: impl SqlSafeStr, ) -> impl Future<Output = Result<Transaction<'_, Self::Database>, Error>> + Send + '_

where Self: Sized,

Begin a new transaction with a custom statement.

Returns a Transaction for controlling and tracking the new transaction.

Returns an error if the connection is already in a transaction or if statement does not put the connection into a transaction.

fn is_in_transaction(&self) -> bool

Returns true if the connection is currently in a transaction.

Note: Automatic Rollbacks May Not Be Counted

Certain database errors (such as a serializable isolation failure) can cause automatic rollbacks of a transaction which may not be indicated in the return value of this method.

fn transaction<'a, F, R, E>( &'a mut self, callback: F, ) -> impl Future<Output = Result<R, E>> + Send + 'a

where for<'c> F: FnOnce(&'c mut Transaction<'_, Self::Database>) -> BoxFuture<'c, Result<R, E>> + 'a + Send + Sync, Self: Sized, R: Send, E: From<Error> + Send,

Execute the function inside a transaction.

If the function returns an error, the transaction will be rolled back. If it does not return an error, the transaction will be committed.

Example

use sqlx::postgres::{PgConnection, PgRow};
use sqlx::Connection;

conn.transaction(|txn| Box::pin(async move {
    sqlx::query("select * from ..").fetch_all(&mut **txn).await
})).await

fn cached_statements_size(&self) -> usize

where Self::Database: HasStatementCache,

The number of statements currently cached in the connection.

fn clear_cached_statements( &mut self, ) -> impl Future<Output = Result<(), Error>> + Send + '_

where Self::Database: HasStatementCache,

Removes all statements from the cache, closing them on the server if needed.

fn connect( url: &str, ) -> impl Future<Output = Result<Self, Error>> + Send + 'static

where Self: Sized,

Establish a new database connection.

A value of Options is parsed from the provided connection string. This parsing is database-specific.

fn connect_with( options: &Self::Options, ) -> impl Future<Output = Result<Self, Error>> + Send + '_

where Self: Sized,

Establish a new database connection with the provided options.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors