Skip to main content

diesel_async/sync_connection_wrapper/
mod.rs

1//! This module contains a wrapper type
2//! that provides a [`crate::AsyncConnection`]
3//! implementation for types that implement
4//! [`diesel::Connection`]. Using this type
5//! might be useful for the following usecases:
6//!
7//! * using a sync Connection implementation in async context
8//! * using the same code base for async crates needing multiple backends
9use futures_core::future::BoxFuture;
10use std::error::Error;
11
12#[cfg(feature = "sqlite")]
13mod sqlite;
14
15/// This is a helper trait that allows to customize the
16/// spawning blocking tasks as part of the
17/// [`SyncConnectionWrapper`] type. By default a
18/// tokio runtime and its spawn_blocking function is used.
19pub trait SpawnBlocking {
20    /// This function should allow to execute a
21    /// given blocking task without blocking the caller
22    /// to get the result
23    fn spawn_blocking<'a, R>(
24        &mut self,
25        task: impl FnOnce() -> R + Send + 'static,
26    ) -> BoxFuture<'a, Result<R, Box<dyn Error + Send + Sync + 'static>>>
27    where
28        R: Send + 'static;
29
30    /// This function should be used to construct
31    /// a new runtime instance
32    fn get_runtime() -> Self;
33}
34
35/// A wrapper of a [`diesel::connection::Connection`] usable in async context.
36///
37/// It implements AsyncConnection if [`diesel::connection::Connection`] fulfils requirements:
38/// * it's a [`diesel::connection::LoadConnection`]
39/// * its [`diesel::connection::Connection::Backend`] has a [`diesel::query_builder::BindCollector`] implementing [`diesel::query_builder::MoveableBindCollector`]
40/// * its [`diesel::connection::LoadConnection::Row`] implements [`diesel::row::IntoOwnedRow`]
41///
42/// Internally this wrapper type will use `spawn_blocking` on tokio
43/// to execute the request on the inner connection. This implies a
44/// dependency on tokio and that the runtime is running.
45///
46/// Note that only SQLite is supported at the moment.
47///
48/// # Examples
49///
50/// ```rust
51/// # include!("../doctest_setup.rs");
52/// use diesel_async::RunQueryDsl;
53/// use schema::users;
54///
55/// async fn some_async_fn() {
56/// # let database_url = database_url();
57///          use diesel_async::AsyncConnection;
58///          use diesel::sqlite::SqliteConnection;
59///          let mut conn =
60///          SyncConnectionWrapper::<SqliteConnection>::establish(&database_url).await.unwrap();
61/// # create_tables(&mut conn).await;
62///
63///          let all_users = users::table.load::<(i32, String)>(&mut conn).await.unwrap();
64/// #         assert_eq!(all_users.len(), 2);
65/// }
66///
67/// # #[cfg(feature = "sqlite")]
68/// # #[tokio::main]
69/// # async fn main() {
70/// #    some_async_fn().await;
71/// # }
72/// ```
73#[cfg(feature = "tokio")]
74pub type SyncConnectionWrapper<C, B = self::implementation::Tokio> =
75    self::implementation::SyncConnectionWrapper<C, B>;
76
77/// A wrapper of a [`diesel::connection::Connection`] usable in async context.
78///
79/// It implements AsyncConnection if [`diesel::connection::Connection`] fulfils requirements:
80/// * it's a [`diesel::connection::LoadConnection`]
81/// * its [`diesel::connection::Connection::Backend`] has a [`diesel::query_builder::BindCollector`] implementing [`diesel::query_builder::MoveableBindCollector`]
82/// * its [`diesel::connection::LoadConnection::Row`] implements [`diesel::row::IntoOwnedRow`]
83///
84/// Internally this wrapper type will use `spawn_blocking` on given type implementing [`SpawnBlocking`] trait
85/// to execute the request on the inner connection.
86#[cfg(not(feature = "tokio"))]
87pub use self::implementation::SyncConnectionWrapper;
88
89pub use self::implementation::SyncTransactionManagerWrapper;
90
91mod implementation {
92    use crate::AsyncMultiConnectionHelper;
93    use crate::{AsyncConnection, AsyncConnectionCore, SimpleAsyncConnection, TransactionManager};
94    use diesel::backend::{Backend, DieselReserveSpecialization};
95    use diesel::connection::{CacheSize, Instrumentation, MultiConnectionHelper};
96    use diesel::connection::{
97        Connection, LoadConnection, TransactionManagerStatus, WithMetadataLookup,
98    };
99    use diesel::query_builder::bind_collector::BindData;
100    use diesel::query_builder::{
101        AsQuery, CollectedQuery, MoveableBindCollector, QueryBuilder, QueryFragment, QueryId,
102    };
103    use diesel::row::IntoOwnedRow;
104    use diesel::sql_types::TypeMetadata;
105    use diesel::{ConnectionResult, QueryResult};
106    use futures_core::stream::BoxStream;
107    use futures_util::{FutureExt, StreamExt, TryFutureExt};
108    use std::marker::PhantomData;
109    use std::sync::{Arc, Mutex};
110
111    use super::*;
112
113    fn from_spawn_blocking_error(
114        error: Box<dyn Error + Send + Sync + 'static>,
115    ) -> diesel::result::Error {
116        diesel::result::Error::DatabaseError(
117            diesel::result::DatabaseErrorKind::UnableToSendCommand,
118            Box::new(error.to_string()),
119        )
120    }
121
122    pub struct SyncConnectionWrapper<C, S> {
123        inner: Arc<Mutex<C>>,
124        runtime: S,
125    }
126
127    impl<C, S> SimpleAsyncConnection for SyncConnectionWrapper<C, S>
128    where
129        C: diesel::connection::Connection + 'static,
130        S: SpawnBlocking + Send,
131    {
132        async fn batch_execute(&mut self, query: &str) -> QueryResult<()> {
133            let query = query.to_string();
134            self.spawn_blocking(move |inner| inner.batch_execute(query.as_str()))
135                .await
136        }
137    }
138
139    impl<C, S, MD, O> AsyncConnectionCore for SyncConnectionWrapper<C, S>
140    where
141        // Backend bounds
142        <C as Connection>::Backend: std::default::Default + DieselReserveSpecialization,
143        <C::Backend as Backend>::QueryBuilder: std::default::Default,
144        // Connection bounds
145        C: Connection + LoadConnection + WithMetadataLookup + 'static,
146        <C as Connection>::TransactionManager: Send,
147        // BindCollector bounds
148        MD: BindData,
149        for<'a> <C::Backend as Backend>::BindCollector<'a>:
150            MoveableBindCollector<C::Backend, BindData = MD> + std::default::Default,
151        // Row bounds
152        O: 'static + Send + for<'conn> diesel::row::Row<'conn, C::Backend>,
153        for<'conn, 'query> <C as LoadConnection>::Row<'conn, 'query>:
154            IntoOwnedRow<'conn, <C as Connection>::Backend, OwnedRow = O>,
155        // SpawnBlocking bounds
156        S: SpawnBlocking + Send,
157    {
158        type LoadFuture<'conn, 'query> = BoxFuture<'conn, QueryResult<Self::Stream<'conn, 'query>>>;
159        type ExecuteFuture<'conn, 'query> = BoxFuture<'conn, QueryResult<usize>>;
160        type Stream<'conn, 'query> = BoxStream<'static, QueryResult<Self::Row<'conn, 'query>>>;
161        type Row<'conn, 'query> = O;
162        type Backend = <C as Connection>::Backend;
163
164        fn load<'conn, 'query, T>(&'conn mut self, source: T) -> Self::LoadFuture<'conn, 'query>
165        where
166            T: AsQuery + 'query,
167            T::Query: QueryFragment<Self::Backend> + QueryId + 'query,
168        {
169            self.execute_with_prepared_query(source.as_query(), |conn, query| {
170                use diesel::row::IntoOwnedRow;
171                let mut cache = <<<C as LoadConnection>::Row<'_, '_> as IntoOwnedRow<
172                    <C as Connection>::Backend,
173                >>::Cache as Default>::default();
174                let cursor = conn.load(&query)?;
175
176                let size_hint = cursor.size_hint();
177                let mut out = Vec::with_capacity(size_hint.1.unwrap_or(size_hint.0));
178                // we use an explicit loop here to easily propagate possible errors
179                // as early as possible
180                for row in cursor {
181                    out.push(Ok(IntoOwnedRow::into_owned(row?, &mut cache)));
182                }
183
184                Ok(out)
185            })
186            .map_ok(|rows| futures_util::stream::iter(rows).boxed())
187            .boxed()
188        }
189
190        fn execute_returning_count<'query, T>(
191            &mut self,
192            source: T,
193        ) -> Self::ExecuteFuture<'_, 'query>
194        where
195            T: QueryFragment<Self::Backend> + QueryId,
196        {
197            self.execute_with_prepared_query(source, |conn, query| {
198                conn.execute_returning_count(&query)
199            })
200        }
201    }
202
203    impl<C, S, MD, O> AsyncConnection for SyncConnectionWrapper<C, S>
204    where
205        // Backend bounds
206        <C as Connection>::Backend: std::default::Default + DieselReserveSpecialization,
207        <C::Backend as Backend>::QueryBuilder: std::default::Default,
208        // Connection bounds
209        C: Connection + LoadConnection + WithMetadataLookup + 'static,
210        <C as Connection>::TransactionManager: Send,
211        // BindCollector bounds
212        MD: BindData,
213        for<'a> <C::Backend as Backend>::BindCollector<'a>:
214            MoveableBindCollector<C::Backend, BindData = MD> + std::default::Default,
215        // Row bounds
216        O: 'static + Send + for<'conn> diesel::row::Row<'conn, C::Backend>,
217        for<'conn, 'query> <C as LoadConnection>::Row<'conn, 'query>:
218            IntoOwnedRow<'conn, <C as Connection>::Backend, OwnedRow = O>,
219        // SpawnBlocking bounds
220        S: SpawnBlocking + Send,
221    {
222        type TransactionManager =
223            SyncTransactionManagerWrapper<<C as Connection>::TransactionManager>;
224
225        async fn establish(database_url: &str) -> ConnectionResult<Self> {
226            let database_url = database_url.to_string();
227            let mut runtime = S::get_runtime();
228
229            runtime
230                .spawn_blocking(move || C::establish(&database_url))
231                .await
232                .unwrap_or_else(|e| Err(diesel::ConnectionError::BadConnection(e.to_string())))
233                .map(move |c| SyncConnectionWrapper::with_runtime(c, runtime))
234        }
235
236        fn transaction_state(
237            &mut self,
238        ) -> &mut <Self::TransactionManager as TransactionManager<Self>>::TransactionStateData
239        {
240            self.exclusive_connection().transaction_state()
241        }
242
243        fn instrumentation(&mut self) -> &mut dyn Instrumentation {
244            // there should be no other pending future when this is called
245            // that means there is only one instance of this arc and
246            // we can simply access the inner data
247            if let Some(inner) = Arc::get_mut(&mut self.inner) {
248                inner
249                    .get_mut()
250                    .unwrap_or_else(|p| p.into_inner())
251                    .instrumentation()
252            } else {
253                panic!("Cannot access shared instrumentation")
254            }
255        }
256
257        fn set_instrumentation(&mut self, instrumentation: impl Instrumentation) {
258            // there should be no other pending future when this is called
259            // that means there is only one instance of this arc and
260            // we can simply access the inner data
261            if let Some(inner) = Arc::get_mut(&mut self.inner) {
262                inner
263                    .get_mut()
264                    .unwrap_or_else(|p| p.into_inner())
265                    .set_instrumentation(instrumentation)
266            } else {
267                panic!("Cannot access shared instrumentation")
268            }
269        }
270
271        fn set_prepared_statement_cache_size(&mut self, size: CacheSize) {
272            // there should be no other pending future when this is called
273            // that means there is only one instance of this arc and
274            // we can simply access the inner data
275            if let Some(inner) = Arc::get_mut(&mut self.inner) {
276                inner
277                    .get_mut()
278                    .unwrap_or_else(|p| p.into_inner())
279                    .set_prepared_statement_cache_size(size)
280            } else {
281                panic!("Cannot access shared cache")
282            }
283        }
284    }
285
286    impl<C, S, MD, O> AsyncMultiConnectionHelper for SyncConnectionWrapper<C, S>
287    where
288        C: MultiConnectionHelper,
289        // Backend bounds
290        <C as Connection>::Backend: std::default::Default + DieselReserveSpecialization,
291        <C::Backend as Backend>::QueryBuilder: std::default::Default,
292        // Connection bounds
293        C: Connection + LoadConnection + WithMetadataLookup + 'static,
294        <C as Connection>::TransactionManager: Send,
295        // BindCollector bounds
296        MD: BindData,
297        for<'a> <C::Backend as Backend>::BindCollector<'a>:
298            MoveableBindCollector<C::Backend, BindData = MD> + std::default::Default,
299        // Row bounds
300        O: 'static + Send + for<'conn> diesel::row::Row<'conn, C::Backend>,
301        for<'conn, 'query> <C as LoadConnection>::Row<'conn, 'query>:
302            IntoOwnedRow<'conn, <C as Connection>::Backend, OwnedRow = O>,
303        // SpawnBlocking bounds
304        S: SpawnBlocking + Send,
305    {
306        fn to_any<'a>(
307            lookup: &mut <Self::Backend as TypeMetadata>::MetadataLookup,
308        ) -> &mut (dyn std::any::Any + 'a) {
309            C::to_any(lookup)
310        }
311
312        fn from_any(
313            lookup: &mut dyn std::any::Any,
314        ) -> Option<&mut <Self::Backend as diesel::sql_types::TypeMetadata>::MetadataLookup>
315        {
316            C::from_any(lookup)
317        }
318    }
319
320    /// A wrapper of a diesel transaction manager usable in async context.
321    pub struct SyncTransactionManagerWrapper<T>(PhantomData<T>);
322
323    impl<T, C, S> TransactionManager<SyncConnectionWrapper<C, S>> for SyncTransactionManagerWrapper<T>
324    where
325        SyncConnectionWrapper<C, S>: AsyncConnection,
326        C: Connection + 'static,
327        S: SpawnBlocking,
328        T: diesel::connection::TransactionManager<C> + Send,
329    {
330        type TransactionStateData = T::TransactionStateData;
331
332        async fn begin_transaction(conn: &mut SyncConnectionWrapper<C, S>) -> QueryResult<()> {
333            conn.spawn_blocking(move |inner| T::begin_transaction(inner))
334                .await
335        }
336
337        async fn commit_transaction(conn: &mut SyncConnectionWrapper<C, S>) -> QueryResult<()> {
338            conn.spawn_blocking(move |inner| T::commit_transaction(inner))
339                .await
340        }
341
342        async fn rollback_transaction(conn: &mut SyncConnectionWrapper<C, S>) -> QueryResult<()> {
343            conn.spawn_blocking(move |inner| T::rollback_transaction(inner))
344                .await
345        }
346
347        fn transaction_manager_status_mut(
348            conn: &mut SyncConnectionWrapper<C, S>,
349        ) -> &mut TransactionManagerStatus {
350            T::transaction_manager_status_mut(conn.exclusive_connection())
351        }
352    }
353
354    impl<C, S> SyncConnectionWrapper<C, S> {
355        /// Builds a wrapper with this underlying sync connection
356        pub fn new(connection: C) -> Self
357        where
358            C: Connection,
359            S: SpawnBlocking,
360        {
361            SyncConnectionWrapper {
362                inner: Arc::new(Mutex::new(connection)),
363                runtime: S::get_runtime(),
364            }
365        }
366
367        /// Builds a wrapper with this underlying sync connection
368        /// and runtime for spawning blocking tasks
369        pub fn with_runtime(connection: C, runtime: S) -> Self
370        where
371            C: Connection,
372            S: SpawnBlocking,
373        {
374            SyncConnectionWrapper {
375                inner: Arc::new(Mutex::new(connection)),
376                runtime,
377            }
378        }
379
380        /// Run a operation directly with the inner connection
381        ///
382        /// This function is useful to register custom functions
383        /// and collection for Sqlite for example
384        ///
385        /// # Example
386        ///
387        /// ```rust
388        /// # include!("../doctest_setup.rs");
389        /// # #[tokio::main]
390        /// # async fn main() {
391        /// #     run_test().await.unwrap();
392        /// # }
393        /// #
394        /// # async fn run_test() -> QueryResult<()> {
395        /// #     let mut conn = establish_connection().await;
396        /// conn.spawn_blocking(|conn| {
397        ///    // sqlite.rs sqlite NOCASE only works for ASCII characters,
398        ///    // this collation allows handling UTF-8 (barring locale differences)
399        ///    conn.register_collation("RUSTNOCASE", |rhs, lhs| {
400        ///     rhs.to_lowercase().cmp(&lhs.to_lowercase())
401        ///   })
402        /// }).await
403        ///
404        /// # }
405        /// ```
406        pub fn spawn_blocking<'a, R>(
407            &mut self,
408            task: impl FnOnce(&mut C) -> QueryResult<R> + Send + 'static,
409        ) -> BoxFuture<'a, QueryResult<R>>
410        where
411            C: Connection + 'static,
412            R: Send + 'static,
413            S: SpawnBlocking,
414        {
415            let inner = self.inner.clone();
416            self.runtime
417                .spawn_blocking(move || {
418                    let mut inner = inner.lock().unwrap_or_else(|poison| {
419                        // try to be resilient by providing the guard
420                        inner.clear_poison();
421                        poison.into_inner()
422                    });
423                    task(&mut inner)
424                })
425                .unwrap_or_else(|err| QueryResult::Err(from_spawn_blocking_error(err)))
426                .boxed()
427        }
428
429        fn execute_with_prepared_query<'a, MD, Q, R>(
430            &mut self,
431            query: Q,
432            callback: impl FnOnce(&mut C, &CollectedQuery<MD>) -> QueryResult<R> + Send + 'static,
433        ) -> BoxFuture<'a, QueryResult<R>>
434        where
435            // Backend bounds
436            <C as Connection>::Backend: std::default::Default + DieselReserveSpecialization,
437            <C::Backend as Backend>::QueryBuilder: std::default::Default,
438            // Connection bounds
439            C: Connection + LoadConnection + WithMetadataLookup + 'static,
440            <C as Connection>::TransactionManager: Send,
441            // BindCollector bounds
442            MD: BindData,
443            for<'b> <C::Backend as Backend>::BindCollector<'b>:
444                MoveableBindCollector<C::Backend, BindData = MD> + std::default::Default,
445            // Arguments/Return bounds
446            Q: QueryFragment<C::Backend> + QueryId,
447            R: Send + 'static,
448            // SpawnBlocking bounds
449            S: SpawnBlocking,
450        {
451            let backend = C::Backend::default();
452
453            let (collect_bind_result, collector_data) = {
454                let exclusive = self.inner.clone();
455                let mut inner = exclusive.lock().unwrap_or_else(|poison| {
456                    // try to be resilient by providing the guard
457                    exclusive.clear_poison();
458                    poison.into_inner()
459                });
460                let mut bind_collector =
461                    <<C::Backend as Backend>::BindCollector<'_> as Default>::default();
462                let metadata_lookup = inner.metadata_lookup();
463                let result = query.collect_binds(&mut bind_collector, metadata_lookup, &backend);
464                let collector_data = bind_collector.moveable();
465
466                (result, collector_data)
467            };
468
469            let mut query_builder = <<C::Backend as Backend>::QueryBuilder as Default>::default();
470            let sql = query
471                .to_sql(&mut query_builder, &backend)
472                .map(|_| query_builder.finish());
473            let is_safe_to_cache_prepared = query.is_safe_to_cache_prepared(&backend);
474
475            self.spawn_blocking(|inner| {
476                collect_bind_result?;
477                let query = CollectedQuery::new(sql?, is_safe_to_cache_prepared?, collector_data);
478                callback(inner, &query)
479            })
480        }
481
482        /// Gets an exclusive access to the underlying diesel Connection
483        ///
484        /// It panics in case of shared access.
485        /// This is typically used only used during transaction.
486        pub(self) fn exclusive_connection(&mut self) -> &mut C
487        where
488            C: Connection,
489        {
490            // there should be no other pending future when this is called
491            // that means there is only one instance of this Arc and
492            // we can simply access the inner data
493            if let Some(conn_mutex) = Arc::get_mut(&mut self.inner) {
494                conn_mutex
495                    .get_mut()
496                    .expect("Mutex is poisoned, a thread must have panicked holding it.")
497            } else {
498                panic!("Cannot access shared transaction state")
499            }
500        }
501    }
502
503    #[cfg(any(
504        feature = "deadpool",
505        feature = "bb8",
506        feature = "mobc",
507        feature = "r2d2"
508    ))]
509    impl<C, S> crate::pooled_connection::PoolableConnection for SyncConnectionWrapper<C, S>
510    where
511        Self: AsyncConnection,
512    {
513        fn is_broken(&mut self) -> bool {
514            Self::TransactionManager::is_broken_transaction_manager(self)
515        }
516    }
517
518    #[cfg(feature = "tokio")]
519    pub enum Tokio {
520        Handle(tokio::runtime::Handle),
521        Runtime(tokio::runtime::Runtime),
522    }
523
524    #[cfg(feature = "tokio")]
525    impl SpawnBlocking for Tokio {
526        fn spawn_blocking<'a, R>(
527            &mut self,
528            task: impl FnOnce() -> R + Send + 'static,
529        ) -> BoxFuture<'a, Result<R, Box<dyn Error + Send + Sync + 'static>>>
530        where
531            R: Send + 'static,
532        {
533            let fut = match self {
534                Tokio::Handle(handle) => CancelWrapper {
535                    future: handle.spawn_blocking(task),
536                    handle: handle.clone(),
537                },
538                Tokio::Runtime(runtime) => CancelWrapper {
539                    future: runtime.spawn_blocking(task),
540                    handle: runtime.handle().clone(),
541                },
542            };
543
544            fut.map_err(Box::from).boxed()
545        }
546
547        fn get_runtime() -> Self {
548            if let Ok(handle) = tokio::runtime::Handle::try_current() {
549                Tokio::Handle(handle)
550            } else {
551                let runtime = tokio::runtime::Builder::new_current_thread()
552                    .build()
553                    .unwrap();
554
555                Tokio::Runtime(runtime)
556            }
557        }
558    }
559
560    #[cfg(feature = "tokio")]
561    use std::pin::Pin;
562
563    #[cfg(feature = "tokio")]
564    /// Wrapper around a task that makes sure it finishes before the Future gets cancelled
565    struct CancelWrapper<R> {
566        handle: tokio::runtime::Handle,
567        future: tokio::task::JoinHandle<R>,
568    }
569
570    #[cfg(feature = "tokio")]
571    impl<R> std::future::Future for CancelWrapper<R> {
572        type Output = Result<R, tokio::task::JoinError>;
573
574        fn poll(
575            self: Pin<&mut Self>,
576            cx: &mut std::task::Context<'_>,
577        ) -> std::task::Poll<Self::Output> {
578            let future = Pin::new(&mut self.get_mut().future);
579            future.poll(cx)
580        }
581    }
582
583    #[cfg(feature = "tokio")]
584    impl<R> Drop for CancelWrapper<R> {
585        fn drop(&mut self) {
586            let future = Pin::new(&mut self.future);
587            if !future.is_finished() {
588                tokio::task::block_in_place(|| {
589                    // we don't care about the result, just make sure the task is finished before continuing
590                    let _ = self.handle.block_on(future);
591                });
592            }
593        }
594    }
595}