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}