Skip to main content

diesel_async/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2//! Diesel-async provides async variants of diesel related query functionality
3//!
4//! diesel-async is an extension to diesel itself. It is designed to be used together
5//! with the main diesel crate. It only provides async variants of core diesel traits,
6//! that perform actual io-work.
7//! This includes async counterparts the following traits:
8//! * [`diesel::prelude::RunQueryDsl`](https://docs.diesel.rs/2.3.x/diesel/prelude/trait.RunQueryDsl.html)
9//!   -> [`diesel_async::RunQueryDsl`](crate::RunQueryDsl)
10//! * [`diesel::connection::Connection`](https://docs.diesel.rs/2.3.x/diesel/connection/trait.Connection.html)
11//!   -> [`diesel_async::AsyncConnection`](crate::AsyncConnection)
12//! * [`diesel::query_dsl::UpdateAndFetchResults`](https://docs.diesel.rs/2.3.x/diesel/query_dsl/trait.UpdateAndFetchResults.html)
13//!   -> [`diesel_async::UpdateAndFetchResults`](crate::UpdateAndFetchResults)
14//!
15//! These traits closely mirror their diesel counter parts while providing async functionality.
16//!
17//! In addition to these core traits 3 fully async connection implementations are provided
18//! by diesel-async:
19//!
20//! * [`AsyncMysqlConnection`] (enabled by the `mysql` feature)
21//! * [`AsyncPgConnection`] (enabled by the `postgres` feature)
22//! * [`SyncConnectionWrapper`](sync_connection_wrapper::SyncConnectionWrapper) (enabled by the `sync-connection-wrapper`/`sqlite` feature)
23//!
24//! Ordinary usage of `diesel-async` assumes that you just replace the corresponding sync trait
25//! method calls and connections with their async counterparts.
26//!
27//! ```rust
28//! # include!("./doctest_setup.rs");
29//! #
30//! use diesel::prelude::*;
31//! use diesel_async::{RunQueryDsl, AsyncConnection};
32//!
33//! diesel::table! {
34//!    users(id) {
35//!        id -> Integer,
36//!        name -> Text,
37//!    }
38//! }
39//! #
40//! # #[tokio::main(flavor = "current_thread")]
41//! # async fn main() {
42//! #     run_test().await;
43//! # }
44//! #
45//! # async fn run_test() -> QueryResult<()> {
46//!
47//! use crate::users::dsl::*;
48//!
49//! # let mut connection = establish_connection().await;
50//! # /*
51//! let mut connection = AsyncPgConnection::establish(std::env::var("DATABASE_URL")?).await?;
52//! # */
53//! let data = users
54//!     // use ordinary diesel query dsl here
55//!     .filter(id.gt(0))
56//!     // execute the query via the provided
57//!     // async variant of `diesel_async::RunQueryDsl`
58//!     .load::<(i32, String)>(&mut connection)
59//!     .await?;
60//! let expected_data = vec![
61//!     (1, String::from("Sean")),
62//!     (2, String::from("Tess")),
63//! ];
64//! assert_eq!(expected_data, data);
65//! #     Ok(())
66//! # }
67//! ```
68//!
69//! ## Crate features:
70//!
71//! * `postgres`: Enables the [`AsyncPgConnection`] implementation
72//! * `mysql`: Enables the [`AsyncMysqlConnection`] implementation
73//! * `sqlite`: Enables the [`SyncConnectionWrapper`](crate::sync_connection_wrapper::SyncConnectionWrapper)
74//!   and everything required to work with SQLite
75//! * `sync-connection-wrapper`: Enables the
76//!   [`SyncConnectionWrapper`](crate::sync_connection_wrapper::SyncConnectionWrapper) which allows to
77//!   wrap sync connections from [`diesel`] into async connection wrapper
78//! * `async-connection-wrapper`: Enables the [`AsyncConnectionWrapper`](crate::async_connection_wrapper::AsyncConnectionWrapper)
79//!   which allows
80//!   to use connection implementations from this crate as sync [`diesel::Connection`]
81//! * `migrations`: Enables the [`AsyncMigrationHarness`] to execute migrations via
82//!   [`diesel_migrations`]
83//! * `pool`: Enables general support for connection pools
84//! * `r2d2`: Enables support for pooling via the [`r2d2`] crate
85//! * `bb8`: Enables support for pooling via the [`bb8`] crate
86//! * `mobc`: Enables support for pooling via the [`mobc`] crate
87//! * `deadpool`: Enables support for pooling via the [`deadpool`] crate
88
89#![warn(
90    missing_docs,
91    clippy::cast_possible_wrap,
92    clippy::cast_possible_truncation,
93    clippy::cast_sign_loss
94)]
95
96use diesel::backend::Backend;
97use diesel::connection::{CacheSize, Instrumentation};
98use diesel::query_builder::{AsQuery, QueryFragment, QueryId};
99use diesel::row::Row;
100use diesel::sql_types::TypeMetadata;
101use diesel::{ConnectionResult, QueryResult};
102use futures_core::Stream;
103use futures_util::FutureExt;
104use std::fmt::Debug;
105use std::future::Future;
106use transaction_manager::AsyncFunc;
107
108#[cfg(feature = "async-connection-wrapper")]
109pub mod async_connection_wrapper;
110mod deref_connection;
111#[cfg(feature = "mariadb")]
112mod mariadb;
113#[cfg(feature = "migrations")]
114mod migrations;
115#[cfg(feature = "mysql")]
116mod mysql;
117#[cfg(any(feature = "mysql", feature = "mariadb"))]
118mod mysql_like;
119#[cfg(feature = "postgres")]
120pub mod pg;
121#[cfg(feature = "pool")]
122pub mod pooled_connection;
123mod run_query_dsl;
124#[cfg(any(feature = "postgres", feature = "mysql", feature = "mariadb"))]
125mod stmt_cache;
126#[cfg(feature = "sync-connection-wrapper")]
127pub mod sync_connection_wrapper;
128mod transaction_manager;
129
130#[cfg(feature = "mariadb")]
131#[doc(inline)]
132pub use self::mariadb::AsyncMariadbConnection;
133#[cfg(feature = "mariadb")]
134#[doc(inline)]
135pub use self::mariadb::MariadbCancelToken;
136#[cfg(feature = "mysql")]
137#[doc(inline)]
138pub use self::mysql::AsyncMysqlConnection;
139#[cfg(feature = "mysql")]
140#[doc(inline)]
141pub use self::mysql::MysqlCancelToken;
142#[cfg(feature = "postgres")]
143#[doc(inline)]
144pub use self::pg::AsyncPgConnection;
145#[doc(inline)]
146pub use self::run_query_dsl::*;
147#[doc(hidden)] // for diesel_derives;
148pub use futures_util;
149
150#[doc(inline)]
151#[cfg(feature = "migrations")]
152pub use self::migrations::AsyncMigrationHarness;
153#[doc(inline)]
154pub use self::transaction_manager::{AnsiTransactionManager, TransactionManager};
155
156/// Perform simple operations on a backend.
157///
158/// You should likely use [`AsyncConnection`] instead.
159pub trait SimpleAsyncConnection {
160    /// Execute multiple SQL statements within the same string.
161    ///
162    /// This function is used to execute migrations,
163    /// which may contain more than one SQL statement.
164    fn batch_execute(&mut self, query: &str) -> impl Future<Output = QueryResult<()>> + Send;
165}
166
167/// Core trait for an async database connection
168pub trait AsyncConnectionCore: SimpleAsyncConnection + Send {
169    /// The future returned by `AsyncConnection::execute`
170    type ExecuteFuture<'conn, 'query>: Future<Output = QueryResult<usize>> + Send;
171    /// The future returned by `AsyncConnection::load`
172    type LoadFuture<'conn, 'query>: Future<Output = QueryResult<Self::Stream<'conn, 'query>>> + Send;
173    /// The inner stream returned by `AsyncConnection::load`
174    type Stream<'conn, 'query>: Stream<Item = QueryResult<Self::Row<'conn, 'query>>> + Send;
175    /// The row type used by the stream returned by `AsyncConnection::load`
176    type Row<'conn, 'query>: Row<'conn, Self::Backend>;
177
178    /// The backend this type connects to
179    type Backend: Backend;
180
181    #[doc(hidden)]
182    fn load<'conn, 'query, T>(&'conn mut self, source: T) -> Self::LoadFuture<'conn, 'query>
183    where
184        T: AsQuery + 'query,
185        T::Query: QueryFragment<Self::Backend> + QueryId + 'query;
186
187    #[doc(hidden)]
188    fn execute_returning_count<'conn, 'query, T>(
189        &'conn mut self,
190        source: T,
191    ) -> Self::ExecuteFuture<'conn, 'query>
192    where
193        T: QueryFragment<Self::Backend> + QueryId + 'query;
194
195    // These functions allow the associated types (`ExecuteFuture`, `LoadFuture`, etc.) to
196    // compile without a `where Self: '_` clause. This is needed the because bound causes
197    // lifetime issues when using `transaction()` with generic `AsyncConnection`s.
198    //
199    // See: https://github.com/rust-lang/rust/issues/87479
200    #[doc(hidden)]
201    fn _silence_lint_on_execute_future(_: Self::ExecuteFuture<'_, '_>) {}
202    #[doc(hidden)]
203    fn _silence_lint_on_load_future(_: Self::LoadFuture<'_, '_>) {}
204}
205
206/// An async connection to a database
207///
208/// This trait represents an async database connection. It can be used to query the database through
209/// the query dsl provided by diesel, custom extensions or raw sql queries. It essentially mirrors
210/// the sync diesel [`Connection`](diesel::connection::Connection) implementation
211pub trait AsyncConnection: AsyncConnectionCore + Sized {
212    #[doc(hidden)]
213    type TransactionManager: TransactionManager<Self>;
214
215    /// Establishes a new connection to the database
216    ///
217    /// The argument to this method and the method's behavior varies by backend.
218    /// See the documentation for that backend's connection class
219    /// for details about what it accepts and how it behaves.
220    fn establish(database_url: &str) -> impl Future<Output = ConnectionResult<Self>> + Send;
221
222    /// Executes the given function inside of a database transaction
223    ///
224    /// This function executes the provided closure `f` inside a database
225    /// transaction. If there is already an open transaction for the current
226    /// connection savepoints will be used instead. The connection is committed if
227    /// the closure returns `Ok(_)`, it will be rolled back if it returns `Err(_)`.
228    /// For both cases the original result value will be returned from this function.
229    ///
230    /// If the transaction fails to commit due to a `SerializationFailure` or a
231    /// `ReadOnlyTransaction` a rollback will be attempted.
232    /// If the rollback fails, the error will be returned in a
233    /// [`Error::RollbackErrorOnCommit`](diesel::result::Error::RollbackErrorOnCommit),
234    /// from which you will be able to extract both the original commit error and
235    /// the rollback error.
236    /// In addition, the connection will be considered broken
237    /// as it contains a uncommitted unabortable open transaction. Any further
238    /// interaction with the transaction system will result in an returned error
239    /// in this case.
240    ///
241    /// If the closure returns an `Err(_)` and the rollback fails the function
242    /// will return that rollback error directly, and the transaction manager will
243    /// be marked as broken as it contains a uncommitted unabortable open transaction.
244    ///
245    /// If a nested transaction fails to release the corresponding savepoint
246    /// the error will be returned directly.
247    ///
248    /// **WARNING:** Canceling the returned future does currently **not**
249    /// close an already open transaction. You may end up with a connection
250    /// containing a dangling transaction.
251    ///
252    /// # Example
253    ///
254    /// ```rust
255    /// # include!("doctest_setup.rs");
256    /// use diesel::result::Error;
257    /// use diesel_async::{RunQueryDsl, AsyncConnection};
258    ///
259    /// # #[tokio::main(flavor = "current_thread")]
260    /// # async fn main() {
261    /// #     run_test().await.unwrap();
262    /// # }
263    /// #
264    /// # async fn run_test() -> QueryResult<()> {
265    /// #     use schema::users::dsl::*;
266    /// #     let conn = &mut establish_connection().await;
267    /// conn.transaction::<_, Error, _>(async |conn| {
268    ///     diesel::insert_into(users)
269    ///         .values(name.eq("Ruby"))
270    ///         .execute(conn)
271    ///         .await?;
272    ///
273    ///     let all_names = users.select(name).load::<String>(conn).await?;
274    ///     assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);
275    ///
276    ///     Ok(())
277    /// }).await?;
278    ///
279    /// conn.transaction::<(), _, _>(async |conn| {
280    ///     diesel::insert_into(users)
281    ///         .values(name.eq("Pascal"))
282    ///         .execute(conn)
283    ///         .await?;
284    ///
285    ///     let all_names = users.select(name).load::<String>(conn).await?;
286    ///     assert_eq!(vec!["Sean", "Tess", "Ruby", "Pascal"], all_names);
287    ///
288    ///     // If we want to roll back the transaction, but don't have an
289    ///     // actual error to return, we can return `RollbackTransaction`.
290    ///     Err(Error::RollbackTransaction)
291    /// }).await;
292    ///
293    /// let all_names = users.select(name).load::<String>(conn).await?;
294    /// assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);
295    /// #     Ok(())
296    /// # }
297    /// ```
298    fn transaction<'a, 'conn, R, E, F>(
299        &'conn mut self,
300        callback: F,
301    ) -> impl Future<Output = Result<R, E>> + Send + 'conn
302    where
303        for<'r> F: AsyncFnOnce(&'r mut Self) -> Result<R, E>
304            + AsyncFunc<&'r mut Self, Result<R, E>, Fut: Send>
305            + Send
306            + 'a,
307        E: From<diesel::result::Error> + Send + 'a,
308        R: Send + 'a,
309        'a: 'conn,
310    {
311        Self::TransactionManager::transaction(self, callback)
312    }
313
314    /// Creates a transaction that will never be committed. This is useful for
315    /// tests. Panics if called while inside of a transaction or
316    /// if called with a connection containing a broken transaction
317    fn begin_test_transaction(&mut self) -> impl Future<Output = QueryResult<()>> + Send {
318        use diesel::connection::TransactionManagerStatus;
319
320        async {
321            match Self::TransactionManager::transaction_manager_status_mut(self) {
322                TransactionManagerStatus::Valid(valid_status) => {
323                    assert_eq!(None, valid_status.transaction_depth())
324                }
325                TransactionManagerStatus::InError => panic!("Transaction manager in error"),
326            };
327            Self::TransactionManager::begin_transaction(self).await?;
328            // set the test transaction flag
329            // to prevent that this connection gets dropped in connection pools
330            // Tests commonly set the poolsize to 1 and use `begin_test_transaction`
331            // to prevent modifications to the schema
332            Self::TransactionManager::transaction_manager_status_mut(self)
333                .set_test_transaction_flag();
334            Ok(())
335        }
336    }
337
338    /// Executes the given function inside a transaction, but does not commit
339    /// it. Panics if the given function returns an error.
340    ///
341    /// # Example
342    ///
343    /// ```rust
344    /// # include!("doctest_setup.rs");
345    /// use diesel::result::Error;
346    /// use diesel_async::{RunQueryDsl, AsyncConnection};
347    ///
348    /// # #[tokio::main(flavor = "current_thread")]
349    /// # async fn main() {
350    /// #     run_test().await.unwrap();
351    /// # }
352    /// #
353    /// # async fn run_test() -> QueryResult<()> {
354    /// #     use schema::users::dsl::*;
355    /// #     let conn = &mut establish_connection().await;
356    /// conn.test_transaction::<_, Error, _>(async |conn| {
357    ///     diesel::insert_into(users)
358    ///         .values(name.eq("Ruby"))
359    ///         .execute(conn)
360    ///         .await?;
361    ///
362    ///     let all_names = users.select(name).load::<String>(conn).await?;
363    ///     assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);
364    ///
365    ///     Ok(())
366    /// }).await;
367    ///
368    /// // Even though we returned `Ok`, the transaction wasn't committed.
369    /// let all_names = users.select(name).load::<String>(conn).await?;
370    /// assert_eq!(vec!["Sean", "Tess"], all_names);
371    /// #     Ok(())
372    /// # }
373    /// ```
374    fn test_transaction<'conn, 'a, R, E, F>(
375        &'conn mut self,
376        f: F,
377    ) -> impl Future<Output = R> + Send + 'conn
378    where
379        for<'r> F: AsyncFnOnce(&'r mut Self) -> Result<R, E>
380            + AsyncFunc<&'r mut Self, Result<R, E>, Fut: Send>
381            + Send
382            + 'a,
383        E: Debug + Send + 'a,
384        R: Send + 'a,
385        'a: 'conn,
386    {
387        use futures_util::TryFutureExt;
388        let (user_result_tx, user_result_rx) = std::sync::mpsc::channel();
389        self.transaction::<R, _, _>(async |conn| {
390            f(conn)
391                .map_err(|_| diesel::result::Error::RollbackTransaction)
392                .and_then(move |r| {
393                    let _ = user_result_tx.send(r);
394                    std::future::ready(Err(diesel::result::Error::RollbackTransaction))
395                })
396                .await
397        })
398        .then(move |_r| {
399            let r = user_result_rx
400                .try_recv()
401                .expect("Transaction did not succeed");
402            std::future::ready(r)
403        })
404    }
405
406    #[doc(hidden)]
407    fn transaction_state(
408        &mut self,
409    ) -> &mut <Self::TransactionManager as TransactionManager<Self>>::TransactionStateData;
410
411    #[doc(hidden)]
412    fn instrumentation(&mut self) -> &mut dyn Instrumentation;
413
414    /// Set a specific [`Instrumentation`] implementation for this connection
415    fn set_instrumentation(&mut self, instrumentation: impl Instrumentation);
416
417    /// Set the prepared statement cache size to [`CacheSize`] for this connection
418    fn set_prepared_statement_cache_size(&mut self, size: CacheSize);
419}
420
421/// `AsyncMultiConnectionHelper` is an async copy of `MultiConnectionHelper` trait.
422/// It is used to support async MultiConnection implementations.
423pub trait AsyncMultiConnectionHelper: AsyncConnectionCore {
424    /// Convert the lookup type to any
425    fn to_any<'a>(
426        lookup: &mut <Self::Backend as TypeMetadata>::MetadataLookup,
427    ) -> &mut (dyn std::any::Any + 'a);
428
429    /// Get the lookup type from any
430    fn from_any(
431        lookup: &mut dyn std::any::Any,
432    ) -> Option<&mut <Self::Backend as TypeMetadata>::MetadataLookup>;
433}
434
435#[doc(hidden)]
436#[macro_export]
437#[cfg(feature = "pool")]
438macro_rules! expand_pool {
439        ($($tt:tt)*) => {$($tt)*};
440    }
441
442#[doc(hidden)]
443#[macro_export]
444#[cfg(not(feature = "pool"))]
445macro_rules! expand_pool {
446    ($($tt:tt)*) => {};
447}