rocket_db_pools/diesel.rs
1//! Re-export of [`diesel`] with prelude types overridden with `async` variants
2//! from [`diesel_async`].
3//!
4//! # Usage
5//!
6//! To use `async` `diesel` support provided here, enable the following
7//! dependencies in your `Cargo.toml`:
8//!
9//! ```toml
10//! [dependencies]
11//! rocket = "=0.6.0-rc.1"
12//! diesel = "2.4.0"
13//!
14//! [dependencies.rocket_db_pools]
15//! version = "=0.4.0-rc.1"
16//! features = ["diesel_mysql"]
17//! ```
18//!
19//! Then, import `rocket_db_pools::diesel::prelude::*` as well as the
20//! appropriate pool type and, optionally, [`QueryResult`]. To use macros or
21//! `diesel` functions, use `diesel::` directly. That is, _do not_ import
22//! `rocket_db_pools::diesel`. Doing so will, by design, cause import errors.
23//!
24//! # Example
25//!
26//! ```rust
27//! # #[macro_use] extern crate rocket;
28//! # #[cfg(feature = "diesel_mysql")] {
29//! use rocket_db_pools::{Database, Connection};
30//! use rocket_db_pools::diesel::{QueryResult, MysqlPool, prelude::*};
31//!
32//! #[derive(Database)]
33//! #[database("diesel_mysql")]
34//! struct Db(MysqlPool);
35//!
36//! #[derive(Queryable, Insertable)]
37//! #[diesel(table_name = posts)]
38//! struct Post {
39//! id: i64,
40//! title: String,
41//! published: bool,
42//! }
43//!
44//! diesel::table! {
45//! posts (id) {
46//! id -> BigInt,
47//! title -> Text,
48//! published -> Bool,
49//! }
50//! }
51//!
52//! #[get("/")]
53//! async fn list(mut db: Connection<Db>) -> QueryResult<String> {
54//! let post_ids: Vec<i64> = posts::table
55//! .select(posts::id)
56//! .load(&mut db)
57//! .await?;
58//!
59//! Ok(format!("{post_ids:?}"))
60//! }
61//! # }
62//! ```
63
64/// The [`diesel`] prelude with `sync`-only traits replaced with their
65/// [`diesel_async`] variants.
66pub mod prelude {
67 #[doc(inline)]
68 pub use diesel::prelude::*;
69
70 #[doc(inline)]
71 pub use diesel_async::{AsyncConnection, RunQueryDsl, SaveChangesDsl};
72}
73
74#[doc(hidden)]
75pub use diesel::*;
76
77#[doc(hidden)]
78pub use diesel_async::{RunQueryDsl, SaveChangesDsl, *};
79
80#[doc(hidden)]
81#[cfg(feature = "diesel_postgres")]
82pub use diesel_async::pg;
83
84#[doc(inline)]
85pub use diesel_async::pooled_connection::deadpool::Pool;
86
87#[doc(inline)]
88pub use diesel_async::async_connection_wrapper::AsyncConnectionWrapper;
89
90#[doc(inline)]
91#[cfg(feature = "diesel_mysql")]
92pub use diesel_async::AsyncMysqlConnection;
93
94#[doc(inline)]
95#[cfg(feature = "diesel_postgres")]
96pub use diesel_async::AsyncPgConnection;
97
98#[doc(inline)]
99#[cfg(feature = "diesel_sqlite")]
100pub use diesel_async::sync_connection_wrapper::SyncConnectionWrapper;
101
102/// Alias of a `Result` with an error type of [`Debug`] for a `diesel::Error`.
103///
104/// `QueryResult` is a [`Responder`](rocket::response::Responder) when `T` (the
105/// `Ok` value) is a `Responder`. By using this alias as a route handler's
106/// return type, the `?` operator can be applied to fallible `diesel` functions
107/// in the route handler while still providing a valid `Responder` return type.
108///
109/// See the [module level docs](self#example) for a usage example.
110///
111/// [`Debug`]: rocket::response::Debug
112pub type QueryResult<T, E = rocket::response::Debug<diesel::result::Error>> = Result<T, E>;
113
114/// Type alias for an `async` pool of MySQL connections for `async` [diesel].
115///
116/// ```rust
117/// # extern crate rocket;
118/// # #[cfg(feature = "diesel_mysql")] {
119/// # use rocket::get;
120/// use rocket_db_pools::{Database, Connection};
121/// use rocket_db_pools::diesel::{MysqlPool, prelude::*};
122///
123/// #[derive(Database)]
124/// #[database("my_mysql_db_name")]
125/// struct Db(MysqlPool);
126///
127/// #[get("/")]
128/// async fn use_db(mut db: Connection<Db>) {
129/// /* .. */
130/// }
131/// # }
132/// ```
133#[cfg(feature = "diesel_mysql")]
134pub type MysqlPool = Pool<AsyncMysqlConnection>;
135
136/// Type alias for an `async` pool of Postgres connections for `async` [diesel].
137///
138/// ```rust
139/// # extern crate rocket;
140/// # #[cfg(feature = "diesel_postgres")] {
141/// # use rocket::get;
142/// use rocket_db_pools::{Database, Connection};
143/// use rocket_db_pools::diesel::{PgPool, prelude::*};
144///
145/// #[derive(Database)]
146/// #[database("my_pg_db_name")]
147/// struct Db(PgPool);
148///
149/// #[get("/")]
150/// async fn use_db(mut db: Connection<Db>) {
151/// /* .. */
152/// }
153/// # }
154/// ```
155#[cfg(feature = "diesel_postgres")]
156pub type PgPool = Pool<AsyncPgConnection>;
157
158/// Type alias for an `async` pool of Sqlite connections for `async` [diesel].
159///
160/// ```rust
161/// # extern crate rocket;
162/// # #[cfg(feature = "diesel_sqlite")] {
163/// # use rocket::get;
164/// use rocket_db_pools::{Database, Connection};
165/// use rocket_db_pools::diesel::{SqlitePool, prelude::*};
166///
167/// #[derive(Database)]
168/// #[database("my_sqlite_db_name")]
169/// struct Db(SqlitePool);
170///
171/// #[get("/")]
172/// async fn use_db(mut db: Connection<Db>) {
173/// /* .. */
174/// }
175/// # }
176/// ```
177#[cfg(feature = "diesel_sqlite")]
178pub type SqlitePool = Pool<SyncConnectionWrapper<SqliteConnection>>;