Trait Connection

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

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

    // Provided methods
    fn transaction<'a, F, R, E>(
        &'a mut self,
        callback: F,
    ) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'a>>
       where F: for<'c> FnOnce(&'c mut Transaction<'_, Self::Database>) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'c>> + 'a + for<'c> Send + for<'c> 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,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>
       where Self::Database: HasStatementCache { ... }
    fn connect(
        url: &str,
    ) -> Pin<Box<dyn Future<Output = Result<Self, Error>> + Send>>
       where Self: Sized { ... }
    fn connect_with(
        options: &Self::Options,
    ) -> Pin<Box<dyn 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) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>>

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, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Checks if a connection to the database is still valid.

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

where Self: Sized,

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 transaction<'a, F, R, E>( &'a mut self, callback: F, ) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'a>>

where F: for<'c> FnOnce(&'c mut Transaction<'_, Self::Database>) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'c>> + 'a + for<'c> Send + for<'c> 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, ) -> Pin<Box<dyn 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, ) -> Pin<Box<dyn Future<Output = Result<Self, Error>> + Send>>

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, ) -> Pin<Box<dyn Future<Output = Result<Self, Error>> + Send + '_>>

where Self: Sized,

Establish a new database connection with the provided options.

Implementors

impl Connection for SqliteConnection

type Database = Sqlite

type Options = SqliteConnectOptions