rocket_db_pools/
diesel.rs

Help
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.5.1"
12//! diesel = "2"
13//!
14//! [dependencies.rocket_db_pools]
15//! version = "0.2.0"
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)]
88#[cfg(feature = "diesel_mysql")]
89pub use diesel_async::AsyncMysqlConnection;
90
91#[doc(inline)]
92#[cfg(feature = "diesel_postgres")]
93pub use diesel_async::AsyncPgConnection;
94
95/// Alias of a `Result` with an error type of [`Debug`] for a `diesel::Error`.
96///
97/// `QueryResult` is a [`Responder`](rocket::response::Responder) when `T` (the
98/// `Ok` value) is a `Responder`. By using this alias as a route handler's
99/// return type, the `?` operator can be applied to fallible `diesel` functions
100/// in the route handler while still providing a valid `Responder` return type.
101///
102/// See the [module level docs](self#example) for a usage example.
103///
104/// [`Debug`]: rocket::response::Debug
105pub type QueryResult<T, E = rocket::response::Debug<diesel::result::Error>> = Result<T, E>;
106
107/// Type alias for an `async` pool of MySQL connections for `async` [diesel].
108///
109/// ```rust
110/// # extern crate rocket;
111/// # #[cfg(feature = "diesel_mysql")] {
112/// # use rocket::get;
113/// use rocket_db_pools::{Database, Connection};
114/// use rocket_db_pools::diesel::{MysqlPool, prelude::*};
115///
116/// #[derive(Database)]
117/// #[database("my_mysql_db_name")]
118/// struct Db(MysqlPool);
119///
120/// #[get("/")]
121/// async fn use_db(mut db: Connection<Db>) {
122///     /* .. */
123/// }
124/// # }
125/// ```
126#[cfg(feature = "diesel_mysql")]
127pub type MysqlPool = Pool<AsyncMysqlConnection>;
128
129/// Type alias for an `async` pool of Postgres connections for `async` [diesel].
130///
131/// ```rust
132/// # extern crate rocket;
133/// # #[cfg(feature = "diesel_postgres")] {
134/// # use rocket::get;
135/// use rocket_db_pools::{Database, Connection};
136/// use rocket_db_pools::diesel::{PgPool, prelude::*};
137///
138/// #[derive(Database)]
139/// #[database("my_pg_db_name")]
140/// struct Db(PgPool);
141///
142/// #[get("/")]
143/// async fn use_db(mut db: Connection<Db>) {
144///     /* .. */
145/// }
146/// # }
147/// ```
148#[cfg(feature = "diesel_postgres")]
149pub type PgPool = Pool<AsyncPgConnection>;
rocket_db_pools/diesel.rs

rocket_db_pools/
diesel.rs
