Skip to main content

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.3.0-rc.1"
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(move |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/v0.6-rc/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//! ### Memcache
183//!
184//! The Memcache driver accepts two additional options in the `url` key:
185//!
186//!   * `connect_timeout` - max number of seconds to wait for a connection from
187//!     the driver's internal pool (defaults to `30`)
188//!   * `timeout` - max number of seconds for a TCP/TLS socket read or write
189//!     (unset by default; ignored for UDP and Unix sockets)
190//!
191//! For example, to set both options:
192//!
193//! ```toml
194//! [default.databases.cache]
195//! url = "memcache://localhost:11211?timeout=0.5&connect_timeout=2"
196//! pool_size = 16
197//! timeout = 5
198//! ```
199//!
200//! The `timeout` key outside of `url` configures Rocket's pool initialization
201//! and connection waits. It defaults to `5` seconds.
202//!
203//! Both URL options accept positive, finite numbers, including fractions.
204//! Invalid values, including values that round to zero or overflow, abort
205//! initialization. If an option is repeated, the first value is used.
206//!
207//! **Note:** Socket timeouts apply to individual reads and writes, and pool
208//! timeouts cannot interrupt synchronous driver calls. Neither URL option
209//! limits the time spent resolving DNS or establishing a TCP connection. As
210//! such, these options do not limit the total time spent executing a command
211//! or cancel commands.
212//!
213//! ## Guard Types
214//!
215//! Once a database has been configured, the `#[database]` attribute can be used
216//! to tie a type in your application to a configured database. The database
217//! attribute accepts a single string parameter that indicates the name of the
218//! database. This corresponds to the database name set as the database's
219//! configuration key.
220//!
221//! See [`ExampleDb`](example::ExampleDb) for everything that the macro
222//! generates. Specifically, it generates:
223//!
224//!   * A [`FromRequest`] implementation for the decorated type.
225//!   * A [`Sentinel`](rocket::Sentinel) implementation for the decorated type.
226//!   * A [`fairing()`](example::ExampleDb::fairing()) method to initialize the
227//!     database.
228//!   * A [`run()`](example::ExampleDb::run()) method to execute blocking
229//!     database operations in an `async`-safe manner.
230//!   * A [`pool()`](example::ExampleDb::pool()) method to retrieve the
231//!     backing connection pool.
232//!
233//! The attribute can only be applied to tuple structs with one field. The
234//! internal type of the structure must implement [`Poolable`].
235//!
236//! ```rust
237//! # #[macro_use] extern crate rocket_sync_db_pools;
238//! # #[cfg(feature = "diesel_sqlite_pool")]
239//! # mod test {
240//! use rocket_sync_db_pools::diesel;
241//!
242//! #[database("my_db")]
243//! struct MyDatabase(diesel::SqliteConnection);
244//! # }
245//! ```
246//!
247//! Other databases can be used by specifying their respective [`Poolable`]
248//! type:
249//!
250//! ```rust
251//! # #[macro_use] extern crate rocket_sync_db_pools;
252//! # #[cfg(feature = "postgres_pool")]
253//! # mod test {
254//! use rocket_sync_db_pools::postgres;
255//!
256//! #[database("my_pg_db")]
257//! struct MyPgDatabase(postgres::Client);
258//! # }
259//! ```
260//!
261//! The fairing returned from the generated `fairing()` method _must_ be
262//! attached for the request guard implementation to succeed. Putting the pieces
263//! together, a use of the `#[database]` attribute looks as follows:
264//!
265//! ```rust
266//! # #[macro_use] extern crate rocket;
267//! # #[macro_use] extern crate rocket_sync_db_pools;
268//! #
269//! # #[cfg(feature = "diesel_sqlite_pool")] {
270//! # use rocket::figment::{value::{Map, Value}, util::map};
271//! use rocket_sync_db_pools::diesel;
272//!
273//! #[database("my_db")]
274//! struct MyDatabase(diesel::SqliteConnection);
275//!
276//! #[launch]
277//! fn rocket() -> _ {
278//! #   let db: Map<_, Value> = map![
279//! #        "url" => "db.sqlite".into(), "pool_size" => 10.into()
280//! #   ];
281//! #   let figment = rocket::Config::figment().merge(("databases", map!["my_db" => db]));
282//!     rocket::custom(figment).attach(MyDatabase::fairing())
283//! }
284//! # }
285//! ```
286//!
287//! ## Handlers
288//!
289//! Finally, use your type as a request guard in a handler to retrieve a
290//! connection wrapper for the database:
291//!
292//! ```rust
293//! # #[macro_use] extern crate rocket;
294//! # #[macro_use] extern crate rocket_sync_db_pools;
295//! #
296//! # #[cfg(feature = "diesel_sqlite_pool")]
297//! # mod test {
298//! # use rocket_sync_db_pools::diesel;
299//! #[database("my_db")]
300//! struct MyDatabase(diesel::SqliteConnection);
301//!
302//! #[get("/")]
303//! fn my_handler(conn: MyDatabase) {
304//!     // ...
305//! }
306//! # }
307//! ```
308//!
309//! A connection can be retrieved and used with the `run()` method:
310//!
311//! ```rust
312//! # #[macro_use] extern crate rocket;
313//! # #[macro_use] extern crate rocket_sync_db_pools;
314//! #
315//! # #[cfg(feature = "diesel_sqlite_pool")]
316//! # mod test {
317//! # use rocket_sync_db_pools::diesel;
318//! # type Data = ();
319//! #[database("my_db")]
320//! struct MyDatabase(diesel::SqliteConnection);
321//!
322//! fn load_from_db(conn: &diesel::SqliteConnection) -> Data {
323//!     // Do something with connection, return some data.
324//!     # ()
325//! }
326//!
327//! #[get("/")]
328//! async fn my_handler(mut conn: MyDatabase) -> Data {
329//!     conn.run(|c| load_from_db(c)).await
330//! }
331//! # }
332//! ```
333//!
334//! # Database Support
335//!
336//! Built-in support is provided for many popular databases and drivers. Support
337//! can be easily extended by [`Poolable`] implementations.
338//!
339//! ## Provided
340//!
341//! The list below includes all presently supported database adapters and their
342//! corresponding [`Poolable`] type.
343//!
344// Note: Keep this table in sync with site/guide/6-state.md
345//! | Kind     | Driver                | Version   | `Poolable` Type                | Feature                |
346//! |----------|-----------------------|-----------|--------------------------------|------------------------|
347//! | Sqlite   | [Diesel]              | `2`       | [`diesel::SqliteConnection`]   | `diesel_sqlite_pool`   |
348//! | Postgres | [Diesel]              | `2`       | [`diesel::PgConnection`]       | `diesel_postgres_pool` |
349//! | MySQL    | [Diesel]              | `2`       | [`diesel::MysqlConnection`]    | `diesel_mysql_pool`    |
350//! | Postgres | [Rust-Postgres]       | `0.19`    | [`postgres::Client`]           | `postgres_pool`        |
351//! | Sqlite   | [`Rusqlite`]          | `0.42`    | [`rusqlite::Connection`]       | `sqlite_pool`          |
352//! | Memcache | [`memcache`]          | `0.21`    | [`memcache::Client`]           | `memcache_pool`        |
353//!
354//! [Diesel]: https://diesel.rs
355//! [`diesel::SqliteConnection`]: https://docs.rs/diesel/2/diesel/sqlite/struct.SqliteConnection.html
356//! [`diesel::PgConnection`]: https://docs.rs/diesel/2/diesel/pg/struct.PgConnection.html
357//! [`diesel::MysqlConnection`]: https://docs.rs/diesel/2/diesel/mysql/struct.MysqlConnection.html
358//! [Rust-Postgres]: https://github.com/sfackler/rust-postgres
359//! [`postgres::Client`]: https://docs.rs/postgres/0.19/postgres/struct.Client.html
360//! [`Rusqlite`]: https://github.com/jgallagher/rusqlite
361//! [`rusqlite::Connection`]: https://docs.rs/rusqlite/0.42/rusqlite/struct.Connection.html
362//! [`diesel::PgConnection`]: http://docs.diesel.rs/diesel/pg/struct.PgConnection.html
363//! [`memcache`]: https://github.com/aisk/rust-memcache
364//! [`memcache::Client`]: https://docs.rs/memcache/0.21/memcache/struct.Client.html
365//!
366//! The above table lists all the supported database adapters in this library.
367//! In order to use particular `Poolable` type that's included in this library,
368//! you must first enable the feature listed in the "Feature" column. The
369//! interior type of your decorated database type should match the type in the
370//! "`Poolable` Type" column.
371//!
372//! ## Extending
373//!
374//! Extending Rocket's support to your own custom database adapter (or other
375//! database-like struct that can be pooled by `r2d2`) is as easy as
376//! implementing the [`Poolable`] trait. See the documentation for [`Poolable`]
377//! for more details on how to implement it.
378//!
379//! [`FromRequest`]: rocket::request::FromRequest
380//! [request guards]: rocket::request::FromRequest
381//! [`Poolable`]: crate::Poolable
382
383#![doc(html_root_url = "https://api.rocket.rs/v0.6-rc/rocket_sync_db_pools")]
384#![doc(html_favicon_url = "https://rocket.rs/images/favicon.ico")]
385#![doc(html_logo_url = "https://rocket.rs/images/logo-boxed.png")]
386#![cfg_attr(nightly, feature(doc_cfg))]
387
388#[doc(hidden)]
389#[macro_use]
390pub extern crate rocket;
391
392#[cfg(any(
393    feature = "diesel_sqlite_pool",
394    feature = "diesel_postgres_pool",
395    feature = "diesel_mysql_pool"
396))]
397pub use diesel;
398
399#[cfg(feature = "postgres_pool")] pub use postgres;
400#[cfg(feature = "postgres_pool")] pub use r2d2_postgres;
401
402#[cfg(feature = "sqlite_pool")] pub use rusqlite;
403#[cfg(feature = "sqlite_pool")] pub use r2d2_sqlite;
404
405#[cfg(feature = "memcache_pool")] pub use memcache;
406
407pub use r2d2;
408
409mod poolable;
410mod config;
411mod error;
412mod connection;
413
414pub use self::poolable::{Poolable, PoolResult};
415#[cfg(feature = "memcache_pool")]
416pub use self::poolable::memcache_pool::MemcacheConnectionManager;
417pub use self::config::Config;
418pub use self::error::Error;
419
420pub use rocket_sync_db_pools_codegen::*;
421pub use self::connection::*;
422
423/// Example of code generated by the `#[database]` attribute.
424#[cfg(all(doc, feature = "diesel_sqlite_pool"))]
425pub mod example {
426    use crate::diesel;
427
428    /// Example of code generated by the `#[database]` attribute.
429    ///
430    /// This implementation of `ExampleDb` was generated by:
431    ///
432    /// ```rust
433    /// use rocket_sync_db_pools::{database, diesel};
434    ///
435    /// #[database("example")]
436    /// pub struct ExampleDb(diesel::SqliteConnection);
437    /// ```
438    pub struct ExampleDb(crate::Connection<Self, diesel::SqliteConnection>);
439
440    impl ExampleDb {
441        /// Returns a fairing that initializes the database connection pool
442        /// associated with `Self`.
443        ///
444        /// The fairing _must_ be attached before `Self` can be used as a
445        /// request guard.
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_sync_db_pools::diesel;
455        ///
456        /// #[database("my_db")]
457        /// struct MyConn(diesel::SqliteConnection);
458        ///
459        /// #[launch]
460        /// fn rocket() -> _ {
461        ///     rocket::build().attach(MyConn::fairing())
462        /// }
463        /// # }
464        /// ```
465        pub fn fairing() -> impl crate::rocket::fairing::Fairing {
466            <crate::ConnectionPool<Self, diesel::SqliteConnection>>::fairing(
467                "'example' Database Pool",
468                "example",
469            )
470        }
471
472        /// Returns an opaque type that represents the connection pool backing
473        /// connections of type `Self` _as long as_ the fairing returned by
474        /// [`Self::fairing()`] is attached and has run on `__rocket`.
475        ///
476        /// The returned pool is `Clone`. Values of type `Self` can be retrieved
477        /// from the pool by calling `pool.get().await` which has the same
478        /// signature and semantics as [`Self::get_one()`].
479        ///
480        /// # Example
481        ///
482        /// ```rust
483        /// # #[macro_use] extern crate rocket;
484        /// # #[macro_use] extern crate rocket_sync_db_pools;
485        /// #
486        /// # #[cfg(feature = "diesel_sqlite_pool")] {
487        /// use rocket::tokio::{task, time};
488        /// use rocket::fairing::AdHoc;
489        /// use rocket_sync_db_pools::diesel;
490        ///
491        /// #[database("my_db")]
492        /// struct MyConn(diesel::SqliteConnection);
493        ///
494        /// #[launch]
495        /// fn rocket() -> _ {
496        ///     rocket::build()
497        ///         .attach(MyConn::fairing())
498        ///         .attach(AdHoc::try_on_ignite("Background DB", |rocket| async {
499        ///             let pool = match MyConn::pool(&rocket) {
500        ///                 Some(pool) => pool.clone(),
501        ///                 None => return Err(rocket)
502        ///             };
503        ///
504        ///             // Start a background task that runs some database
505        ///             // operation every 10 seconds. If a connection isn't
506        ///             // available, retries 10 + timeout seconds later.
507        ///             tokio::task::spawn(async move {
508        ///                 loop {
509        ///                     time::sleep(time::Duration::from_secs(10)).await;
510        ///                     if let Some(conn) = pool.get().await {
511        ///                         conn.run(|c| { /* perform db ops */ }).await;
512        ///                     }
513        ///                 }
514        ///             });
515        ///
516        ///             Ok(rocket)
517        ///         }))
518        /// }
519        /// # }
520        /// ```
521        pub fn pool<P: crate::rocket::Phase>(
522            __rocket: &crate::rocket::Rocket<P>,
523        ) -> Option<&crate::ConnectionPool<Self, diesel::SqliteConnection>>
524        {
525            <crate::ConnectionPool<Self, diesel::SqliteConnection>>::pool(
526                &__rocket,
527            )
528        }
529
530        /// Runs the provided function `__f` in an async-safe blocking thread.
531        /// The function is supplied with a mutable reference to the raw
532        /// connection (a value of type `&mut Self.0`). `.await`ing the return
533        /// value of this function yields the value returned by `__f`.
534        ///
535        /// # Example
536        ///
537        /// ```rust
538        /// # #[macro_use] extern crate rocket;
539        /// # #[macro_use] extern crate rocket_sync_db_pools;
540        /// #
541        /// # #[cfg(feature = "diesel_sqlite_pool")] {
542        /// use rocket_sync_db_pools::diesel;
543        ///
544        /// #[database("my_db")]
545        /// struct MyConn(diesel::SqliteConnection);
546        ///
547        /// #[get("/")]
548        /// async fn f(conn: MyConn) {
549        ///     // The type annotation is illustrative and isn't required.
550        ///     let result = conn.run(|c: &mut diesel::SqliteConnection| {
551        ///         // Use `c`.
552        ///     }).await;
553        /// }
554        /// # }
555        /// ```
556        pub async fn run<F, R>(&self, __f: F) -> R
557        where
558            F: FnOnce(&mut diesel::SqliteConnection) -> R + Send + 'static,
559            R: Send + 'static,
560        {
561            self.0.run(__f).await
562        }
563
564        /// Retrieves a connection of type `Self` from the `rocket` instance.
565        /// Returns `Some` as long as `Self::fairing()` has been attached and
566        /// there is a connection available within at most `timeout` seconds.
567        pub async fn get_one<P: crate::rocket::Phase>(
568            __rocket: &crate::rocket::Rocket<P>,
569        ) -> Option<Self> {
570            <crate::ConnectionPool<Self, diesel::SqliteConnection>>::get_one(
571                &__rocket,
572            )
573            .await
574            .map(Self)
575        }
576    }
577
578    /// Retrieves a connection from the database pool or fails with a
579    /// `Status::ServiceUnavailable` if doing so times out.
580    impl<'r> crate::rocket::request::FromRequest<'r> for ExampleDb {
581        type Error = ();
582        #[allow(
583            clippy::let_unit_value,
584            clippy::no_effect_underscore_binding,
585            clippy::shadow_same,
586            clippy::type_complexity,
587            clippy::type_repetition_in_bounds,
588            clippy::used_underscore_binding
589        )]
590        fn from_request<'life0, 'async_trait>(
591            __r: &'r crate::rocket::request::Request<'life0>,
592        ) -> ::core::pin::Pin<
593            Box<
594                dyn ::core::future::Future<
595                        Output = crate::rocket::request::Outcome<Self, ()>,
596                    > + ::core::marker::Send
597                    + 'async_trait,
598            >,
599        >
600        where
601            'r: 'async_trait,
602            'life0: 'async_trait,
603            Self: 'async_trait,
604        {
605            Box::pin(async move {
606                if let ::core::option::Option::Some(__ret) = ::core::option::Option::None::<
607                    crate::rocket::request::Outcome<Self, ()>,
608                > {
609                    return __ret;
610                }
611                let __r = __r;
612                let __ret: crate::rocket::request::Outcome<Self, ()> = {
613                    < crate :: Connection < Self , diesel :: SqliteConnection > >
614                        :: from_request (__r) . await . map (Self)
615                };
616                #[allow(unreachable_code)]
617                __ret
618            })
619        }
620    }
621    impl crate::rocket::Sentinel for ExampleDb {
622        fn abort(
623            __r: &crate::rocket::Rocket<crate::rocket::Ignite>,
624        ) -> bool {
625            <crate::Connection<Self, diesel::SqliteConnection>>::abort(__r)
626        }
627    }
628}