Trait AsyncConnection 

pub trait AsyncConnection: AsyncConnectionCore + Sized {
    // Required methods
    fn establish(
        database_url: &str,
    ) -> impl Future<Output = ConnectionResult<Self>> + Send;
    fn set_instrumentation(&mut self, instrumentation: impl Instrumentation);
    fn set_prepared_statement_cache_size(&mut self, size: CacheSize);

    // Provided methods
    fn transaction<'a, 'conn, R, E, F>(
        &'conn mut self,
        callback: F,
    ) -> BoxFuture<'conn, Result<R, E>>
       where F: for<'r> FnOnce(&'r mut Self) -> ScopedBoxFuture<'a, 'r, Result<R, E>> + Send + 'a,
             E: From<Error> + Send + 'a,
             R: Send + 'a,
             'a: 'conn { ... }
    fn begin_test_transaction(
        &mut self,
    ) -> impl Future<Output = QueryResult<()>> + Send { ... }
    fn test_transaction<'conn, 'a, R, E, F>(
        &'conn mut self,
        f: F,
    ) -> impl Future<Output = R> + Send + 'conn
       where F: for<'r> FnOnce(&'r mut Self) -> ScopedBoxFuture<'a, 'r, Result<R, E>> + Send + 'a,
             E: Debug + Send + 'a,
             R: Send + 'a,
             'a: 'conn { ... }
}

An async connection to a database

This trait represents an async database connection. It can be used to query the database through the query dsl provided by diesel, custom extensions or raw sql queries. It essentially mirrors the sync diesel Connection implementation

Required Methods

fn establish( database_url: &str, ) -> impl Future<Output = ConnectionResult<Self>> + Send

Establishes a new connection to the database

The argument to this method and the method’s behavior varies by backend. See the documentation for that backend’s connection class for details about what it accepts and how it behaves.

fn set_instrumentation(&mut self, instrumentation: impl Instrumentation)

Set a specific Instrumentation implementation for this connection

fn set_prepared_statement_cache_size(&mut self, size: CacheSize)

Set the prepared statement cache size to CacheSize for this connection

Provided Methods

fn transaction<'a, 'conn, R, E, F>( &'conn mut self, callback: F, ) -> BoxFuture<'conn, Result<R, E>>

where F: for<'r> FnOnce(&'r mut Self) -> ScopedBoxFuture<'a, 'r, Result<R, E>> + Send + 'a, E: From<Error> + Send + 'a, R: Send + 'a, 'a: 'conn,

Executes the given function inside of a database transaction

This function executes the provided closure f inside a database transaction. If there is already an open transaction for the current connection savepoints will be used instead. The connection is committed if the closure returns Ok(_), it will be rolled back if it returns Err(_). For both cases the original result value will be returned from this function.

If the transaction fails to commit due to a SerializationFailure or a ReadOnlyTransaction a rollback will be attempted. If the rollback fails, the error will be returned in a Error::RollbackErrorOnCommit, from which you will be able to extract both the original commit error and the rollback error. In addition, the connection will be considered broken as it contains a uncommitted unabortable open transaction. Any further interaction with the transaction system will result in an returned error in this case.

If the closure returns an Err(_) and the rollback fails the function will return that rollback error directly, and the transaction manager will be marked as broken as it contains a uncommitted unabortable open transaction.

If a nested transaction fails to release the corresponding savepoint the error will be returned directly.

WARNING: Canceling the returned future does currently not close an already open transaction. You may end up with a connection containing a dangling transaction.

Example

use diesel::result::Error;
use scoped_futures::ScopedFutureExt;
use diesel_async::{RunQueryDsl, AsyncConnection};

conn.transaction::<_, Error, _>(|conn| async move {
    diesel::insert_into(users)
        .values(name.eq("Ruby"))
        .execute(conn)
        .await?;

    let all_names = users.select(name).load::<String>(conn).await?;
    assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);

    Ok(())
}.scope_boxed()).await?;

conn.transaction::<(), _, _>(|conn| async move {
    diesel::insert_into(users)
        .values(name.eq("Pascal"))
        .execute(conn)
        .await?;

    let all_names = users.select(name).load::<String>(conn).await?;
    assert_eq!(vec!["Sean", "Tess", "Ruby", "Pascal"], all_names);

    // If we want to roll back the transaction, but don't have an
    // actual error to return, we can return `RollbackTransaction`.
    Err(Error::RollbackTransaction)
}.scope_boxed()).await;

let all_names = users.select(name).load::<String>(conn).await?;
assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);

fn begin_test_transaction( &mut self, ) -> impl Future<Output = QueryResult<()>> + Send

Creates a transaction that will never be committed. This is useful for tests. Panics if called while inside of a transaction or if called with a connection containing a broken transaction

fn test_transaction<'conn, 'a, R, E, F>( &'conn mut self, f: F, ) -> impl Future<Output = R> + Send + 'conn

where F: for<'r> FnOnce(&'r mut Self) -> ScopedBoxFuture<'a, 'r, Result<R, E>> + Send + 'a, E: Debug + Send + 'a, R: Send + 'a, 'a: 'conn,

Executes the given function inside a transaction, but does not commit it. Panics if the given function returns an error.

Example

use diesel::result::Error;
use scoped_futures::ScopedFutureExt;
use diesel_async::{RunQueryDsl, AsyncConnection};

conn.test_transaction::<_, Error, _>(|conn| async move {
    diesel::insert_into(users)
        .values(name.eq("Ruby"))
        .execute(conn)
        .await?;

    let all_names = users.select(name).load::<String>(conn).await?;
    assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);

    Ok(())
}.scope_boxed()).await;

// Even though we returned `Ok`, the transaction wasn't committed.
let all_names = users.select(name).load::<String>(conn).await?;
assert_eq!(vec!["Sean", "Tess"], all_names);

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

impl AsyncConnection for AsyncMysqlConnection

Available on crate feature mysql only.

impl AsyncConnection for AsyncPgConnection

Available on crate feature postgres only.

impl<C> AsyncConnection for C

where C: DerefMut + Send, C::Target: AsyncConnection,