Trait sqlx::Connection

source · 
pub trait Connection: Send {
    type Database: Database;
    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 { ... }
}
Expand description

Represents a single database connection.

Required Associated Types§

source

type Database: Database

source

type Options: ConnectOptions<Connection = Self>

Required Methods§

source

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.

source

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

Checks if a connection to the database is still valid.

source

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.

source

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§

source

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
source

fn cached_statements_size(&self) -> usize
where Self::Database: HasStatementCache,

The number of statements currently cached in the connection.

source

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.

source

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.

source

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§