Struct SyncConnectionWrapper

pub struct SyncConnectionWrapper<C> { /* private fields */ }

Available on crate feature sync-connection-wrapper only.

A wrapper of a diesel::connection::Connection usable in async context.

It implements AsyncConnection if diesel::connection::Connection fullfils requirements:

• it’s a diesel::connection::LoadConnection
• its diesel::connection::Connection::Backend has a diesel::query_builder::BindCollector implementing diesel::query_builder::MoveableBindCollector
• its diesel::connection::LoadConnection::Row implements diesel::row::IntoOwnedRow

Internally this wrapper type will use spawn_blocking on tokio to execute the request on the inner connection. This implies a dependency on tokio and that the runtime is running.

Note that only SQLite is supported at the moment.

Examples

use diesel_async::RunQueryDsl;
use schema::users;

async fn some_async_fn() {
         use diesel_async::AsyncConnection;
         use diesel::sqlite::SqliteConnection;
         let mut conn =
         SyncConnectionWrapper::<SqliteConnection>::establish(&database_url).await.unwrap();

         let all_users = users::table.load::<(i32, String)>(&mut conn).await.unwrap();
}

Implementations

impl SyncConnectionWrapper<SqliteConnection>

pub async fn immediate_transaction<'a, R, E, F>(&mut self, f: F) -> 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,

Available on crate feature sqlite only.

Run a transaction with BEGIN IMMEDIATE

This method will return an error if a transaction is already open.

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.immediate_transaction(|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

pub async fn exclusive_transaction<'a, R, E, F>(&mut self, f: F) -> 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,

Available on crate feature sqlite only.

Run a transaction with BEGIN EXCLUSIVE

This method will return an error if a transaction is already open.

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.exclusive_transaction(|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

impl<C> SyncConnectionWrapper<C>

pub fn new(connection: C) -> Self

where C: Connection,

Builds a wrapper with this underlying sync connection

pub fn spawn_blocking<'a, R>( &mut self, task: impl FnOnce(&mut C) -> QueryResult<R> + Send + 'static, ) -> BoxFuture<'a, QueryResult<R>>

where C: Connection + 'static, R: Send + 'static,

Run a operation directly with the inner connection

This function is usful to register custom functions and collection for Sqlite for example

Example

conn.spawn_blocking(|conn| {
   // sqlite.rs sqlite NOCASE only works for ASCII characters,
   // this collation allows handling UTF-8 (barring locale differences)
   conn.register_collation("RUSTNOCASE", |rhs, lhs| {
    rhs.to_lowercase().cmp(&lhs.to_lowercase())
  })
}).await

Trait Implementations

impl<C, MD, O> AsyncConnection for SyncConnectionWrapper<C>

where <C as Connection>::Backend: Default + DieselReserveSpecialization, <C::Backend as Backend>::QueryBuilder: Default, C: Connection + LoadConnection + WithMetadataLookup + 'static, <C as Connection>::TransactionManager: Send, MD: Send + 'static, for<'a> <C::Backend as Backend>::BindCollector<'a>: MoveableBindCollector<C::Backend, BindData = MD> + Default, O: 'static + Send + for<'conn> Row<'conn, C::Backend>, for<'conn, 'query> <C as LoadConnection>::Row<'conn, 'query>: IntoOwnedRow<'conn, <C as Connection>::Backend, OwnedRow = O>,

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

The future returned by AsyncConnection::load

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

The future returned by AsyncConnection::execute

type Stream<'conn, 'query> = Pin<Box<dyn Stream<Item = Result<<SyncConnectionWrapper<C> as AsyncConnection>::Row<'conn, 'query>, Error>> + Send>>

The inner stream returned by AsyncConnection::load

type Row<'conn, 'query> = O

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

type Backend = <C as Connection>::Backend

The backend this type connects to

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

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

Set a specific Instrumentation implementation for this connection

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

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

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

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

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

impl<C> SimpleAsyncConnection for SyncConnectionWrapper<C>

where C: Connection + 'static,

fn batch_execute<'life0, 'life1, 'async_trait>( &'life0 mut self, query: &'life1 str, ) -> Pin<Box<dyn Future<Output = QueryResult<()>> + Send + 'async_trait>>

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

Execute multiple SQL statements within the same string.

impl<T, C> TransactionManager<SyncConnectionWrapper<C>> for SyncTransactionManagerWrapper<T>

where SyncConnectionWrapper<C>: AsyncConnection, C: Connection + 'static, T: TransactionManager<C> + Send,

type TransactionStateData = <T as TransactionManager<C>>::TransactionStateData

Data stored as part of the connection implementation to track the current transaction state of a connection

fn begin_transaction<'life0, 'async_trait>( conn: &'life0 mut SyncConnectionWrapper<C>, ) -> Pin<Box<dyn Future<Output = QueryResult<()>> + Send + 'async_trait>>

where 'life0: 'async_trait,

Begin a new transaction or savepoint

fn commit_transaction<'life0, 'async_trait>( conn: &'life0 mut SyncConnectionWrapper<C>, ) -> Pin<Box<dyn Future<Output = QueryResult<()>> + Send + 'async_trait>>

where 'life0: 'async_trait,

Commit the inner-most transaction or savepoint

fn rollback_transaction<'life0, 'async_trait>( conn: &'life0 mut SyncConnectionWrapper<C>, ) -> Pin<Box<dyn Future<Output = QueryResult<()>> + Send + 'async_trait>>

where 'life0: 'async_trait,

Rollback the inner-most transaction or savepoint

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

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

Executes the given function inside of a database transaction