rocket_sync_db_pools/lib.rs
1//! Traits, utilities, and a macro for easy database connection pooling.
2//!
3//! # Overview
4//!
5//! This crate provides traits, utilities, and a procedural macro for
6//! configuring and accessing database connection pools in Rocket. A _database
7//! connection pool_ is a data structure that maintains active database
8//! connections for later use in the application. This implementation is backed
9//! by [`r2d2`] and exposes connections through request guards.
10//!
11//! Databases are individually configured through Rocket's regular configuration
12//! mechanisms. Connecting a Rocket application to a database using this library
13//! occurs in three simple steps:
14//!
15//! 1. Configure your databases in `Rocket.toml`.
16//! (see [Configuration](#configuration))
17//! 2. Associate a request guard type and fairing with each database.
18//! (see [Guard Types](#guard-types))
19//! 3. Use the request guard to retrieve a connection in a handler.
20//! (see [Handlers](#handlers))
21//!
22//! For a list of supported databases, see [Provided Databases](#provided). This
23//! support can be easily extended by implementing the [`Poolable`] trait. See
24//! [Extending](#extending) for more.
25//!
26//! ## Example
27//!
28//! Before using this library, the feature corresponding to your database type
29//! in `rocket_sync_db_pools` must be enabled:
30//!
31//! ```toml
32//! [dependencies.rocket_sync_db_pools]
33//! version = "0.1.0"
34//! features = ["diesel_sqlite_pool"]
35//! ```
36//!
37//! See [Provided](#provided) for a list of supported database and their
38//! associated feature name.
39//!
40//! In whichever configuration source you choose, configure a `databases`
41//! dictionary with an internal dictionary for each database, here `sqlite_logs`
42//! in a TOML source:
43//!
44//! ```toml
45//! [default.databases]
46//! sqlite_logs = { url = "/path/to/database.sqlite" }
47//! ```
48//!
49//! In your application's source code, one-time:
50//!
51//! ```rust
52//! # #[macro_use] extern crate rocket;
53//! # #[cfg(feature = "diesel_sqlite_pool")]
54//! # mod test {
55//! use rocket_sync_db_pools::{database, diesel};
56//!
57//! #[database("sqlite_logs")]
58//! struct LogsDbConn(diesel::SqliteConnection);
59//!
60//! #[launch]
61//! fn rocket() -> _ {
62//! rocket::build().attach(LogsDbConn::fairing())
63//! }
64//! # } fn main() {}
65//! ```
66//!
67//! Whenever a connection to the database is needed:
68//!
69//! ```rust
70//! # #[macro_use] extern crate rocket;
71//! # #[macro_use] extern crate rocket_sync_db_pools;
72//! #
73//! # #[cfg(feature = "diesel_sqlite_pool")]
74//! # mod test {
75//! # use rocket_sync_db_pools::diesel;
76//! #
77//! # #[database("sqlite_logs")]
78//! # struct LogsDbConn(diesel::SqliteConnection);
79//! #
80//! # type Logs = ();
81//! # type Result<T> = std::result::Result<T, ()>;
82//! #
83//! #[get("/logs/<id>")]
84//! async fn get_logs(conn: LogsDbConn, id: usize) -> Result<Logs> {
85//! # /*
86//! conn.run(|c| Logs::by_id(c, id)).await
87//! # */
88//! # Ok(())
89//! }
90//! # } fn main() {}
91//! ```
92//!
93//! # Usage
94//!
95//! ## Configuration
96//!
97//! Databases can be configured as any other values. Using the default
98//! configuration provider, either via `Rocket.toml` or environment variables.
99//! You can also use a custom provider.
100//!
101//! ### `Rocket.toml`
102//!
103//! To configure a database via `Rocket.toml`, add a table for each database to
104//! the `databases` table where the key is a name of your choice. The table
105//! should have a `url` key and, optionally, `pool_size` and `timeout` keys.
106//! This looks as follows:
107//!
108//! ```toml
109//! # Option 1:
110//! [global.databases]
111//! sqlite_db = { url = "db.sqlite" }
112//!
113//! # Option 2:
114//! [global.databases.my_db]
115//! url = "postgres://root:root@localhost/my_db"
116//!
117//! # With `pool_size` and `timeout` keys:
118//! [global.databases.sqlite_db]
119//! url = "db.sqlite"
120//! pool_size = 20
121//! timeout = 5
122//! ```
123//!
124//! The table _requires_ one key:
125//!
126//! * `url` - the URl to the database
127//!
128//! Additionally, all configurations accept the following _optional_ keys:
129//!
130//! * `pool_size` - the size of the pool, i.e., the number of connections to
131//! pool (defaults to the configured number of workers * 4)
132//! * `timeout` - max number of seconds to wait for a connection to become
133//! available (defaults to `5`)
134//!
135//! Additional options may be required or supported by other adapters.
136//!
137//! ### Procedurally
138//!
139//! Databases can also be configured procedurally via `rocket::custom()`.
140//! The example below does just this:
141//!
142//! ```rust
143//! # #[cfg(feature = "diesel_sqlite_pool")] {
144//! # use rocket::launch;
145//! use rocket::figment::{value::{Map, Value}, util::map};
146//!
147//! #[launch]
148//! fn rocket() -> _ {
149//! let db: Map<_, Value> = map! {
150//! "url" => "db.sqlite".into(),
151//! "pool_size" => 10.into(),
152//! "timeout" => 5.into(),
153//! };
154//!
155//! let figment = rocket::Config::figment()
156//! .merge(("databases", map!["my_db" => db]));
157//!
158//! rocket::custom(figment)
159//! }
160//! # rocket();
161//! # }
162//! ```
163//!
164//! ### Environment Variables
165//!
166//! Lastly, databases can be configured via environment variables by specifying
167//! the `databases` table as detailed in the [Environment Variables
168//! configuration
169//! guide](https://rocket.rs/master/guide/configuration/#environment-variables):
170//!
171//! ```bash
172//! ROCKET_DATABASES='{my_db={url="db.sqlite"}}'
173//! ```
174//!
175//! Multiple databases can be specified in the `ROCKET_DATABASES` environment variable
176//! as well by comma separating them:
177//!
178//! ```bash
179//! ROCKET_DATABASES='{my_db={url="db.sqlite"},my_pg_db={url="postgres://root:root@localhost/my_pg_db"}}'
180//! ```
181//!
182//! ## Guard Types
183//!
184//! Once a database has been configured, the `#[database]` attribute can be used
185//! to tie a type in your application to a configured database. The database
186//! attribute accepts a single string parameter that indicates the name of the
187//! database. This corresponds to the database name set as the database's
188//! configuration key.
189//!
190//! See [`ExampleDb`](example::ExampleDb) for everything that the macro
191//! generates. Specifically, it generates:
192//!
193//! * A [`FromRequest`] implementation for the decorated type.
194//! * A [`Sentinel`](rocket::Sentinel) implementation for the decorated type.
195//! * A [`fairing()`](example::ExampleDb::fairing()) method to initialize the
196//! database.
197//! * A [`run()`](example::ExampleDb::run()) method to execute blocking
198//! database operations in an `async`-safe manner.
199//! * A [`pool()`](example::ExampleDb::pool()) method to retrieve the
200//! backing connection pool.
201//!
202//! The attribute can only be applied to tuple structs with one field. The
203//! internal type of the structure must implement [`Poolable`].
204//!
205//! ```rust
206//! # #[macro_use] extern crate rocket_sync_db_pools;
207//! # #[cfg(feature = "diesel_sqlite_pool")]
208//! # mod test {
209//! use rocket_sync_db_pools::diesel;
210//!
211//! #[database("my_db")]
212//! struct MyDatabase(diesel::SqliteConnection);
213//! # }
214//! ```
215//!
216//! Other databases can be used by specifying their respective [`Poolable`]
217//! type:
218//!
219//! ```rust
220//! # #[macro_use] extern crate rocket_sync_db_pools;
221//! # #[cfg(feature = "postgres_pool")]
222//! # mod test {
223//! use rocket_sync_db_pools::postgres;
224//!
225//! #[database("my_pg_db")]
226//! struct MyPgDatabase(postgres::Client);
227//! # }
228//! ```
229//!
230//! The fairing returned from the generated `fairing()` method _must_ be
231//! attached for the request guard implementation to succeed. Putting the pieces
232//! together, a use of the `#[database]` attribute looks as follows:
233//!
234//! ```rust
235//! # #[macro_use] extern crate rocket;
236//! # #[macro_use] extern crate rocket_sync_db_pools;
237//! #
238//! # #[cfg(feature = "diesel_sqlite_pool")] {
239//! # use rocket::figment::{value::{Map, Value}, util::map};
240//! use rocket_sync_db_pools::diesel;
241//!
242//! #[database("my_db")]
243//! struct MyDatabase(diesel::SqliteConnection);
244//!
245//! #[launch]
246//! fn rocket() -> _ {
247//! # let db: Map<_, Value> = map![
248//! # "url" => "db.sqlite".into(), "pool_size" => 10.into()
249//! # ];
250//! # let figment = rocket::Config::figment().merge(("databases", map!["my_db" => db]));
251//! rocket::custom(figment).attach(MyDatabase::fairing())
252//! }
253//! # }
254//! ```
255//!
256//! ## Handlers
257//!
258//! Finally, use your type as a request guard in a handler to retrieve a
259//! connection wrapper for the database:
260//!
261//! ```rust
262//! # #[macro_use] extern crate rocket;
263//! # #[macro_use] extern crate rocket_sync_db_pools;
264//! #
265//! # #[cfg(feature = "diesel_sqlite_pool")]
266//! # mod test {
267//! # use rocket_sync_db_pools::diesel;
268//! #[database("my_db")]
269//! struct MyDatabase(diesel::SqliteConnection);
270//!
271//! #[get("/")]
272//! fn my_handler(conn: MyDatabase) {
273//! // ...
274//! }
275//! # }
276//! ```
277//!
278//! A connection can be retrieved and used with the `run()` method:
279//!
280//! ```rust
281//! # #[macro_use] extern crate rocket;
282//! # #[macro_use] extern crate rocket_sync_db_pools;
283//! #
284//! # #[cfg(feature = "diesel_sqlite_pool")]
285//! # mod test {
286//! # use rocket_sync_db_pools::diesel;
287//! # type Data = ();
288//! #[database("my_db")]
289//! struct MyDatabase(diesel::SqliteConnection);
290//!
291//! fn load_from_db(conn: &diesel::SqliteConnection) -> Data {
292//! // Do something with connection, return some data.
293//! # ()
294//! }
295//!
296//! #[get("/")]
297//! async fn my_handler(mut conn: MyDatabase) -> Data {
298//! conn.run(|c| load_from_db(c)).await
299//! }
300//! # }
301//! ```
302//!
303//! # Database Support
304//!
305//! Built-in support is provided for many popular databases and drivers. Support
306//! can be easily extended by [`Poolable`] implementations.
307//!
308//! ## Provided
309//!
310//! The list below includes all presently supported database adapters and their
311//! corresponding [`Poolable`] type.
312//!
313// Note: Keep this table in sync with site/guide/6-state.md
314//! | Kind | Driver | Version | `Poolable` Type | Feature |
315//! |----------|-----------------------|-----------|--------------------------------|------------------------|
316//! | Sqlite | [Diesel] | `2` | [`diesel::SqliteConnection`] | `diesel_sqlite_pool` |
317//! | Postgres | [Diesel] | `2` | [`diesel::PgConnection`] | `diesel_postgres_pool` |
318//! | MySQL | [Diesel] | `2` | [`diesel::MysqlConnection`] | `diesel_mysql_pool` |
319//! | Postgres | [Rust-Postgres] | `0.19` | [`postgres::Client`] | `postgres_pool` |
320//! | Sqlite | [`Rusqlite`] | `0.31` | [`rusqlite::Connection`] | `sqlite_pool` |
321//! | Memcache | [`memcache`] | `0.17` | [`memcache::Client`] | `memcache_pool` |
322//!
323//! [Diesel]: https://diesel.rs
324//! [`diesel::SqliteConnection`]: https://docs.rs/diesel/2/diesel/sqlite/struct.SqliteConnection.html
325//! [`diesel::PgConnection`]: https://docs.rs/diesel/2/diesel/pg/struct.PgConnection.html
326//! [`diesel::MysqlConnection`]: https://docs.rs/diesel/2/diesel/mysql/struct.MysqlConnection.html
327//! [Rust-Postgres]: https://github.com/sfackler/rust-postgres
328//! [`postgres::Client`]: https://docs.rs/postgres/0.19/postgres/struct.Client.html
329//! [`Rusqlite`]: https://github.com/jgallagher/rusqlite
330//! [`rusqlite::Connection`]: https://docs.rs/rusqlite/0.31/rusqlite/struct.Connection.html
331//! [`diesel::PgConnection`]: http://docs.diesel.rs/diesel/pg/struct.PgConnection.html
332//! [`memcache`]: https://github.com/aisk/rust-memcache
333//! [`memcache::Client`]: https://docs.rs/memcache/0.17/memcache/struct.Client.html
334//!
335//! The above table lists all the supported database adapters in this library.
336//! In order to use particular `Poolable` type that's included in this library,
337//! you must first enable the feature listed in the "Feature" column. The
338//! interior type of your decorated database type should match the type in the
339//! "`Poolable` Type" column.
340//!
341//! ## Extending
342//!
343//! Extending Rocket's support to your own custom database adapter (or other
344//! database-like struct that can be pooled by `r2d2`) is as easy as
345//! implementing the [`Poolable`] trait. See the documentation for [`Poolable`]
346//! for more details on how to implement it.
347//!
348//! [`FromRequest`]: rocket::request::FromRequest
349//! [request guards]: rocket::request::FromRequest
350//! [`Poolable`]: crate::Poolable
351
352#![doc(html_root_url = "https://api.rocket.rs/master/rocket_sync_db_pools")]
353#![doc(html_favicon_url = "https://rocket.rs/images/favicon.ico")]
354#![doc(html_logo_url = "https://rocket.rs/images/logo-boxed.png")]
355#![cfg_attr(nightly, feature(doc_cfg))]
356
357#[doc(hidden)]
358#[macro_use]
359pub extern crate rocket;
360
361#[cfg(any(
362 feature = "diesel_sqlite_pool",
363 feature = "diesel_postgres_pool",
364 feature = "diesel_mysql_pool"
365))]
366pub use diesel;
367
368#[cfg(feature = "postgres_pool")] pub use postgres;
369#[cfg(feature = "postgres_pool")] pub use r2d2_postgres;
370
371#[cfg(feature = "sqlite_pool")] pub use rusqlite;
372#[cfg(feature = "sqlite_pool")] pub use r2d2_sqlite;
373
374#[cfg(feature = "memcache_pool")] pub use memcache;
375
376pub use r2d2;
377
378mod poolable;
379mod config;
380mod error;
381mod connection;
382
383pub use self::poolable::{Poolable, PoolResult};
384pub use self::config::Config;
385pub use self::error::Error;
386
387pub use rocket_sync_db_pools_codegen::*;
388pub use self::connection::*;
389
390/// Example of code generated by the `#[database]` attribute.
391#[cfg(all(nightly, doc, feature = "diesel_sqlite_pool"))]
392pub mod example {
393 use crate::diesel;
394
395 /// Example of code generated by the `#[database]` attribute.
396 ///
397 /// This implementation of `ExampleDb` was generated by:
398 ///
399 /// ```rust
400 /// use rocket_sync_db_pools::{database, diesel};
401 ///
402 /// #[database("example")]
403 /// pub struct ExampleDb(diesel::SqliteConnection);
404 /// ```
405 pub struct ExampleDb(crate::Connection<Self, diesel::SqliteConnection>);
406
407 impl ExampleDb {
408 /// Returns a fairing that initializes the database connection pool
409 /// associated with `Self`.
410 ///
411 /// The fairing _must_ be attached before `Self` can be used as a
412 /// request guard.
413 ///
414 /// # Example
415 ///
416 /// ```rust
417 /// # #[macro_use] extern crate rocket;
418 /// # #[macro_use] extern crate rocket_sync_db_pools;
419 /// #
420 /// # #[cfg(feature = "diesel_sqlite_pool")] {
421 /// use rocket_sync_db_pools::diesel;
422 ///
423 /// #[database("my_db")]
424 /// struct MyConn(diesel::SqliteConnection);
425 ///
426 /// #[launch]
427 /// fn rocket() -> _ {
428 /// rocket::build().attach(MyConn::fairing())
429 /// }
430 /// # }
431 /// ```
432 pub fn fairing() -> impl crate::rocket::fairing::Fairing {
433 <crate::ConnectionPool<Self, diesel::SqliteConnection>>::fairing(
434 "'example' Database Pool",
435 "example",
436 )
437 }
438
439 /// Returns an opaque type that represents the connection pool backing
440 /// connections of type `Self` _as long as_ the fairing returned by
441 /// [`Self::fairing()`] is attached and has run on `__rocket`.
442 ///
443 /// The returned pool is `Clone`. Values of type `Self` can be retrieved
444 /// from the pool by calling `pool.get().await` which has the same
445 /// signature and semantics as [`Self::get_one()`].
446 ///
447 /// # Example
448 ///
449 /// ```rust
450 /// # #[macro_use] extern crate rocket;
451 /// # #[macro_use] extern crate rocket_sync_db_pools;
452 /// #
453 /// # #[cfg(feature = "diesel_sqlite_pool")] {
454 /// use rocket::tokio::{task, time};
455 /// use rocket::fairing::AdHoc;
456 /// use rocket_sync_db_pools::diesel;
457 ///
458 /// #[database("my_db")]
459 /// struct MyConn(diesel::SqliteConnection);
460 ///
461 /// #[launch]
462 /// fn rocket() -> _ {
463 /// rocket::build()
464 /// .attach(MyConn::fairing())
465 /// .attach(AdHoc::try_on_ignite("Background DB", |rocket| async {
466 /// let pool = match MyConn::pool(&rocket) {
467 /// Some(pool) => pool.clone(),
468 /// None => return Err(rocket)
469 /// };
470 ///
471 /// // Start a background task that runs some database
472 /// // operation every 10 seconds. If a connection isn't
473 /// // available, retries 10 + timeout seconds later.
474 /// tokio::task::spawn(async move {
475 /// loop {
476 /// time::sleep(time::Duration::from_secs(10)).await;
477 /// if let Some(conn) = pool.get().await {
478 /// conn.run(|c| { /* perform db ops */ }).await;
479 /// }
480 /// }
481 /// });
482 ///
483 /// Ok(rocket)
484 /// }))
485 /// }
486 /// # }
487 /// ```
488 pub fn pool<P: crate::rocket::Phase>(
489 __rocket: &crate::rocket::Rocket<P>,
490 ) -> Option<&crate::ConnectionPool<Self, diesel::SqliteConnection>>
491 {
492 <crate::ConnectionPool<Self, diesel::SqliteConnection>>::pool(
493 &__rocket,
494 )
495 }
496
497 /// Runs the provided function `__f` in an async-safe blocking thread.
498 /// The function is supplied with a mutable reference to the raw
499 /// connection (a value of type `&mut Self.0`). `.await`ing the return
500 /// value of this function yields the value returned by `__f`.
501 ///
502 /// # Example
503 ///
504 /// ```rust
505 /// # #[macro_use] extern crate rocket;
506 /// # #[macro_use] extern crate rocket_sync_db_pools;
507 /// #
508 /// # #[cfg(feature = "diesel_sqlite_pool")] {
509 /// use rocket_sync_db_pools::diesel;
510 ///
511 /// #[database("my_db")]
512 /// struct MyConn(diesel::SqliteConnection);
513 ///
514 /// #[get("/")]
515 /// async fn f(conn: MyConn) {
516 /// // The type annotation is illustrative and isn't required.
517 /// let result = conn.run(|c: &mut diesel::SqliteConnection| {
518 /// // Use `c`.
519 /// }).await;
520 /// }
521 /// # }
522 /// ```
523 pub async fn run<F, R>(&self, __f: F) -> R
524 where
525 F: FnOnce(&mut diesel::SqliteConnection) -> R + Send + 'static,
526 R: Send + 'static,
527 {
528 self.0.run(__f).await
529 }
530
531 /// Retrieves a connection of type `Self` from the `rocket` instance.
532 /// Returns `Some` as long as `Self::fairing()` has been attached and
533 /// there is a connection available within at most `timeout` seconds.
534 pub async fn get_one<P: crate::rocket::Phase>(
535 __rocket: &crate::rocket::Rocket<P>,
536 ) -> Option<Self> {
537 <crate::ConnectionPool<Self, diesel::SqliteConnection>>::get_one(
538 &__rocket,
539 )
540 .await
541 .map(Self)
542 }
543 }
544
545 /// Retrieves a connection from the database pool or fails with a
546 /// `Status::ServiceUnavailable` if doing so times out.
547 impl<'r> crate::rocket::request::FromRequest<'r> for ExampleDb {
548 type Error = ();
549 #[allow(
550 clippy::let_unit_value,
551 clippy::no_effect_underscore_binding,
552 clippy::shadow_same,
553 clippy::type_complexity,
554 clippy::type_repetition_in_bounds,
555 clippy::used_underscore_binding
556 )]
557 fn from_request<'life0, 'async_trait>(
558 __r: &'r crate::rocket::request::Request<'life0>,
559 ) -> ::core::pin::Pin<
560 Box<
561 dyn ::core::future::Future<
562 Output = crate::rocket::request::Outcome<Self, ()>,
563 > + ::core::marker::Send
564 + 'async_trait,
565 >,
566 >
567 where
568 'r: 'async_trait,
569 'life0: 'async_trait,
570 Self: 'async_trait,
571 {
572 Box::pin(async move {
573 if let ::core::option::Option::Some(__ret) = ::core::option::Option::None::<
574 crate::rocket::request::Outcome<Self, ()>,
575 > {
576 return __ret;
577 }
578 let __r = __r;
579 let __ret: crate::rocket::request::Outcome<Self, ()> = {
580 < crate :: Connection < Self , diesel :: SqliteConnection > >
581 :: from_request (__r) . await . map (Self)
582 };
583 #[allow(unreachable_code)]
584 __ret
585 })
586 }
587 }
588 impl crate::rocket::Sentinel for ExampleDb {
589 fn abort(
590 __r: &crate::rocket::Rocket<crate::rocket::Ignite>,
591 ) -> bool {
592 <crate::Connection<Self, diesel::SqliteConnection>>::abort(__r)
593 }
594 }
595}