Trait diesel_async::AsyncConnection

pub trait AsyncConnection:
    SimpleAsyncConnection
    + Sized
    + Send {
    type ExecuteFuture<'conn, 'query>: Future<Output = QueryResult<usize>> + Send
       where Self: 'conn;
    type LoadFuture<'conn, 'query>: Future<Output = QueryResult<Self::Stream<'conn, 'query>>> + Send
       where Self: 'conn;
    type Stream<'conn, 'query>: Stream<Item = QueryResult<Self::Row<'conn, 'query>>> + Send
       where Self: 'conn;
    type Row<'conn, 'query>: Row<'conn, Self::Backend>
       where Self: 'conn;
    type Backend: Backend;

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

    // Provided methods
    fn transaction<'a, 'life0, 'async_trait, R, E, F>(
        &'life0 mut self,
        callback: F,
    ) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'async_trait>>
       where F: for<'r> FnOnce(&'r mut Self) -> ScopedBoxFuture<'a, 'r, Result<R, E>> + Send + 'a + 'async_trait,
             E: From<Error> + Send + 'a + 'async_trait,
             R: Send + 'a + 'async_trait,
             Self: 'async_trait,
             'a: 'async_trait,
             'life0: 'async_trait { ... }
    fn begin_test_transaction<'life0, 'async_trait>(
        &'life0 mut self,
    ) -> Pin<Box<dyn Future<Output = QueryResult<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}

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

type ExecuteFuture<'conn, 'query>: Future<Output = QueryResult<usize>> + Send where Self: 'conn

The future returned by AsyncConnection::execute

type LoadFuture<'conn, 'query>: Future<Output = QueryResult<Self::Stream<'conn, 'query>>> + Send where Self: 'conn

The future returned by AsyncConnection::load

type Stream<'conn, 'query>: Stream<Item = QueryResult<Self::Row<'conn, 'query>>> + Send where Self: 'conn

The inner stream returned by AsyncConnection::load

type Row<'conn, 'query>: Row<'conn, Self::Backend> where Self: 'conn

The row type used by the stream returned by AsyncConnection::load

type Backend: Backend

The backend this type connects to

Required Methods

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

where Self: 'async_trait, 'life0: 'async_trait,

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

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

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

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 scoped_futures::ScopedFutureExt;

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<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = QueryResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

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

Object Safety

This trait is not object safe.

Implementors

impl AsyncConnection for AsyncPgConnection

type LoadFuture<'conn, 'query> = Pin<Box<dyn Future<Output = Result<<AsyncPgConnection as AsyncConnection>::Stream<'conn, 'query>, Error>> + Send + 'query>>

type ExecuteFuture<'conn, 'query> = Pin<Box<dyn Future<Output = Result<usize, Error>> + Send + 'query>>

type Stream<'conn, 'query> = Pin<Box<dyn Stream<Item = Result<PgRow, Error>> + Send>>

type Row<'conn, 'query> = PgRow

type Backend = Pg

impl<C> AsyncConnection for C

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

type ExecuteFuture<'conn, 'query> = <<C as Deref>::Target as AsyncConnection>::ExecuteFuture<'conn, 'query> where C::Target: 'conn, C: 'conn

type LoadFuture<'conn, 'query> = <<C as Deref>::Target as AsyncConnection>::LoadFuture<'conn, 'query> where C::Target: 'conn, C: 'conn

type Stream<'conn, 'query> = <<C as Deref>::Target as AsyncConnection>::Stream<'conn, 'query> where C::Target: 'conn, C: 'conn

type Row<'conn, 'query> = <<C as Deref>::Target as AsyncConnection>::Row<'conn, 'query> where C::Target: 'conn, C: 'conn

type Backend = <<C as Deref>::Target as AsyncConnection>::Backend