Trait diesel_async::AsyncConnection

source · [−]
pub trait AsyncConnection: SimpleAsyncConnection + Sized + Sendwhere
    for<'a, 'b> Self: AsyncConnectionGatWorkaround<'a, 'b, Self::Backend>,{
    type Backend: Backend;

    fn establish<'life0, 'async_trait>(
        database_url: &'life0 str
    ) -> Pin<Box<dyn Future<Output = ConnectionResult<Self>> + Send + 'async_trait>>
    where
        'life0: 'async_trait,
        Self: 'async_trait;

    fn transaction<'life0, 'async_trait, R, E, F>(
        &'life0 mut self,
        callback: F
    ) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'async_trait>>
    where
        F: FnOnce(&mut Self) -> BoxFuture<'_, Result<R, E>> + Send,
        E: From<Error> + Send,
        R: Send,
        R: 'async_trait,
        E: 'async_trait,
        F: 'async_trait,
        'life0: 'async_trait,
        Self: 'async_trait,
    { ... }
    fn begin_test_transaction<'life0, 'async_trait>(
        &'life0 mut self
    ) -> Pin<Box<dyn Future<Output = QueryResult<()>> + Send + 'async_trait>>
    where
        'life0: 'async_trait,
        Self: 'async_trait,
    { ... }
}
Expand description

An async connection to a database

This trait represents a n 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 Associated Types

The backend this type connects to

Required Methods

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.

Provided Methods

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: Cancling 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 futures::FutureExt;

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(())
}.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)
}.boxed()).await;

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

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

Implementors