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

rocket_db_pools/
diesel.rs
