mirror of https://github.com/rwf2/Rocket.git
Rearrange contrib database support modules.
This commit is contained in:
Sergio Benitez
parent
4b09e77ccb
commit
2366bff05f
|
|
@ -1,877 +0,0 @@
|
||||||
//! Traits, utilities, and a macro for easy database connection pooling.
|
|
||||||
//!
|
|
||||||
//! # Overview
|
|
||||||
//!
|
|
||||||
//! This module provides traits, utilities, and a procedural macro that allows
|
|
||||||
//! you to easily connect your Rocket application to databases through
|
|
||||||
//! connection pools. A _database connection pool_ is a data structure that
|
|
||||||
//! maintains active database connections for later use in the application.
|
|
||||||
//! This implementation of connection pooling support is based on
|
|
||||||
//! [`r2d2`] and exposes connections through [request guards]. Databases are
|
|
||||||
//! individually configured through Rocket's regular configuration mechanisms: a
|
|
||||||
//! `Rocket.toml` file, environment variables, or procedurally.
|
|
||||||
//!
|
|
||||||
//! Connecting your Rocket application to a database using this library occurs
|
|
||||||
//! in three simple steps:
|
|
||||||
//!
|
|
||||||
//! 1. Configure your databases in `Rocket.toml`.
|
|
||||||
//! (see [Configuration](#configuration))
|
|
||||||
//! 2. Associate a request guard type and fairing with each database.
|
|
||||||
//! (see [Guard Types](#guard-types))
|
|
||||||
//! 3. Use the request guard to retrieve a connection in a handler.
|
|
||||||
//! (see [Handlers](#handlers))
|
|
||||||
//!
|
|
||||||
//! For a list of supported databases, see [Provided Databases](#provided). This
|
|
||||||
//! support can be easily extended by implementing the [`Poolable`] trait. See
|
|
||||||
//! [Extending](#extending) for more.
|
|
||||||
//!
|
|
||||||
//! ## Example
|
|
||||||
//!
|
|
||||||
//! Before using this library, the feature corresponding to your database type
|
|
||||||
//! in `rocket_contrib` must be enabled:
|
|
||||||
//!
|
|
||||||
//! ```toml
|
|
||||||
//! [dependencies.rocket_contrib]
|
|
||||||
//! version = "0.5.0-dev"
|
|
||||||
//! default-features = false
|
|
||||||
//! features = ["diesel_sqlite_pool"]
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! See [Provided](#provided) for a list of supported database and their
|
|
||||||
//! associated feature name.
|
|
||||||
//!
|
|
||||||
//! In whichever configuration source you choose, configure a `databases`
|
|
||||||
//! dictionary with an internal dictionary for each database, here `sqlite_logs`
|
|
||||||
//! in a TOML source:
|
|
||||||
//!
|
|
||||||
//! ```toml
|
|
||||||
//! [global.databases]
|
|
||||||
//! sqlite_logs = { url = "/path/to/database.sqlite" }
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! In your application's source code, one-time:
|
|
||||||
//!
|
|
||||||
//! ```rust
|
|
||||||
//! #[macro_use] extern crate rocket;
|
|
||||||
//! #[macro_use] extern crate rocket_contrib;
|
|
||||||
//!
|
|
||||||
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
|
||||||
//! # mod test {
|
|
||||||
//! use rocket_contrib::databases::diesel;
|
|
||||||
//!
|
|
||||||
//! #[database("sqlite_logs")]
|
|
||||||
//! struct LogsDbConn(diesel::SqliteConnection);
|
|
||||||
//!
|
|
||||||
//! #[launch]
|
|
||||||
//! fn rocket() -> rocket::Rocket {
|
|
||||||
//! rocket::ignite().attach(LogsDbConn::fairing())
|
|
||||||
//! }
|
|
||||||
//! # } fn main() {}
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! Whenever a connection to the database is needed:
|
|
||||||
//!
|
|
||||||
//! ```rust
|
|
||||||
//! # #[macro_use] extern crate rocket;
|
|
||||||
//! # #[macro_use] extern crate rocket_contrib;
|
|
||||||
//! #
|
|
||||||
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
|
||||||
//! # mod test {
|
|
||||||
//! # use rocket_contrib::databases::diesel;
|
|
||||||
//! #
|
|
||||||
//! # #[database("sqlite_logs")]
|
|
||||||
//! # struct LogsDbConn(diesel::SqliteConnection);
|
|
||||||
//! #
|
|
||||||
//! # type Logs = ();
|
|
||||||
//! # type Result<T> = std::result::Result<T, ()>;
|
|
||||||
//! #
|
|
||||||
//! #[get("/logs/<id>")]
|
|
||||||
//! async fn get_logs(conn: LogsDbConn, id: usize) -> Result<Logs> {
|
|
||||||
//! # /*
|
|
||||||
//! conn.run(|c| Logs::by_id(c, id)).await
|
|
||||||
//! # */
|
|
||||||
//! # Ok(())
|
|
||||||
//! }
|
|
||||||
//! # } fn main() {}
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! # Usage
|
|
||||||
//!
|
|
||||||
//! ## Configuration
|
|
||||||
//!
|
|
||||||
//! Databases can be configured as any other values. Using the default
|
|
||||||
//! configuration provider, either via `Rocket.toml` or environment variables.
|
|
||||||
//! You can also use a custom provider.
|
|
||||||
//!
|
|
||||||
//! ### `Rocket.toml`
|
|
||||||
//!
|
|
||||||
//! To configure a database via `Rocket.toml`, add a table for each database
|
|
||||||
//! to the `databases` table where the key is a name of your choice. The table
|
|
||||||
//! should have a `url` key and, optionally, a `pool_size` key. This looks as
|
|
||||||
//! follows:
|
|
||||||
//!
|
|
||||||
//! ```toml
|
|
||||||
//! # Option 1:
|
|
||||||
//! [global.databases]
|
|
||||||
//! sqlite_db = { url = "db.sqlite" }
|
|
||||||
//!
|
|
||||||
//! # Option 2:
|
|
||||||
//! [global.databases.my_db]
|
|
||||||
//! url = "mysql://root:root@localhost/my_db"
|
|
||||||
//!
|
|
||||||
//! # With a `pool_size` key:
|
|
||||||
//! [global.databases]
|
|
||||||
//! sqlite_db = { url = "db.sqlite", pool_size = 20 }
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! The table _requires_ one key:
|
|
||||||
//!
|
|
||||||
//! * `url` - the URl to the database
|
|
||||||
//!
|
|
||||||
//! Additionally, all configurations accept the following _optional_ keys:
|
|
||||||
//!
|
|
||||||
//! * `pool_size` - the size of the pool, i.e., the number of connections to
|
|
||||||
//! pool (defaults to the configured number of workers * 2)
|
|
||||||
//!
|
|
||||||
//! Additional options may be required or supported by other adapters.
|
|
||||||
//!
|
|
||||||
//! ### Procedurally
|
|
||||||
//!
|
|
||||||
//! Databases can also be configured procedurally via `rocket::custom()`.
|
|
||||||
//! The example below does just this:
|
|
||||||
//!
|
|
||||||
//! ```rust
|
|
||||||
//! # #[cfg(feature = "diesel_sqlite_pool")] {
|
|
||||||
//! use rocket::figment::{value::{Map, Value}, util::map};
|
|
||||||
//!
|
|
||||||
//! #[rocket::launch]
|
|
||||||
//! fn rocket() -> _ {
|
|
||||||
//! let db: Map<_, Value> = map! {
|
|
||||||
//! "url" => "db.sqlite".into(),
|
|
||||||
//! "pool_size" => 10.into()
|
|
||||||
//! };
|
|
||||||
//!
|
|
||||||
//! let figment = rocket::Config::figment()
|
|
||||||
//! .merge(("databases", map!["my_db" => db]));
|
|
||||||
//!
|
|
||||||
//! rocket::custom(figment)
|
|
||||||
//! }
|
|
||||||
//! # rocket();
|
|
||||||
//! # }
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! ### Environment Variables
|
|
||||||
//!
|
|
||||||
//! Lastly, databases can be configured via environment variables by specifying
|
|
||||||
//! the `databases` table as detailed in the [Environment Variables
|
|
||||||
//! configuration
|
|
||||||
//! guide](https://rocket.rs/master/guide/configuration/#environment-variables):
|
|
||||||
//!
|
|
||||||
//! ```bash
|
|
||||||
//! ROCKET_DATABASES='{my_db={url="db.sqlite"}}'
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! Multiple databases can be specified in the `ROCKET_DATABASES` environment variable
|
|
||||||
//! as well by comma separating them:
|
|
||||||
//!
|
|
||||||
//! ```bash
|
|
||||||
//! ROCKET_DATABASES='{my_db={url="db.sqlite"},my_pg_db={url="postgres://root:root@localhost/my_pg_db"}}'
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! ## Guard Types
|
|
||||||
//!
|
|
||||||
//! Once a database has been configured, the `#[database]` attribute can be used
|
|
||||||
//! to tie a type in your application to a configured database. The database
|
|
||||||
//! attributes accepts a single string parameter that indicates the name of the
|
|
||||||
//! database. This corresponds to the database name set as the database's
|
|
||||||
//! configuration key.
|
|
||||||
//!
|
|
||||||
//! The macro generates a [`FromRequest`] implementation for the decorated type,
|
|
||||||
//! allowing the type to be used as a request guard. This implementation
|
|
||||||
//! retrieves a connection from the database pool or fails with a
|
|
||||||
//! `Status::ServiceUnavailable` if connecting to the database times out.
|
|
||||||
//!
|
|
||||||
//! The macro will also generate two inherent methods on the decorated type:
|
|
||||||
//!
|
|
||||||
//! * `fn fairing() -> impl Fairing`
|
|
||||||
//!
|
|
||||||
//! Returns a fairing that initializes the associated database connection
|
|
||||||
//! pool.
|
|
||||||
//!
|
|
||||||
//! * `async fn get_one(&Rocket) -> Option<Self>`
|
|
||||||
//!
|
|
||||||
//! Retrieves a connection wrapper from the configured pool. Returns `Some`
|
|
||||||
//! as long as `Self::fairing()` has been attached.
|
|
||||||
//!
|
|
||||||
//! The attribute can only be applied to unit-like structs with one type. The
|
|
||||||
//! internal type of the structure must implement [`Poolable`].
|
|
||||||
//!
|
|
||||||
//! ```rust
|
|
||||||
//! # extern crate rocket;
|
|
||||||
//! # #[macro_use] extern crate rocket_contrib;
|
|
||||||
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
|
||||||
//! # mod test {
|
|
||||||
//! use rocket_contrib::databases::diesel;
|
|
||||||
//!
|
|
||||||
//! #[database("my_db")]
|
|
||||||
//! struct MyDatabase(diesel::SqliteConnection);
|
|
||||||
//! # }
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! Other databases can be used by specifying their respective [`Poolable`]
|
|
||||||
//! type:
|
|
||||||
//!
|
|
||||||
//! ```rust
|
|
||||||
//! # extern crate rocket;
|
|
||||||
//! # #[macro_use] extern crate rocket_contrib;
|
|
||||||
//! # #[cfg(feature = "postgres_pool")]
|
|
||||||
//! # mod test {
|
|
||||||
//! use rocket_contrib::databases::postgres;
|
|
||||||
//!
|
|
||||||
//! #[database("my_pg_db")]
|
|
||||||
//! struct MyPgDatabase(postgres::Client);
|
|
||||||
//! # }
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! The fairing returned from the generated `fairing()` method _must_ be
|
|
||||||
//! attached for the request guard implementation to succeed. Putting the pieces
|
|
||||||
//! together, a use of the `#[database]` attribute looks as follows:
|
|
||||||
//!
|
|
||||||
//! ```rust
|
|
||||||
//! # #[macro_use] extern crate rocket;
|
|
||||||
//! # #[macro_use] extern crate rocket_contrib;
|
|
||||||
//! #
|
|
||||||
//! # #[cfg(feature = "diesel_sqlite_pool")] {
|
|
||||||
//! # use rocket::figment::{value::{Map, Value}, util::map};
|
|
||||||
//! use rocket_contrib::databases::diesel;
|
|
||||||
//!
|
|
||||||
//! #[database("my_db")]
|
|
||||||
//! struct MyDatabase(diesel::SqliteConnection);
|
|
||||||
//!
|
|
||||||
//! #[launch]
|
|
||||||
//! fn rocket() -> _ {
|
|
||||||
//! # let db: Map<_, Value> = map![
|
|
||||||
//! # "url" => "db.sqlite".into(), "pool_size" => 10.into()
|
|
||||||
//! # ];
|
|
||||||
//! # let figment = rocket::Config::figment().merge(("databases", map!["my_db" => db]));
|
|
||||||
//! rocket::custom(figment).attach(MyDatabase::fairing())
|
|
||||||
//! }
|
|
||||||
//! # }
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! ## Handlers
|
|
||||||
//!
|
|
||||||
//! Finally, use your type as a request guard in a handler to retrieve a
|
|
||||||
//! connection wrapper for the database:
|
|
||||||
//!
|
|
||||||
//! ```rust
|
|
||||||
//! # #[macro_use] extern crate rocket;
|
|
||||||
//! # #[macro_use] extern crate rocket_contrib;
|
|
||||||
//! #
|
|
||||||
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
|
||||||
//! # mod test {
|
|
||||||
//! # use rocket_contrib::databases::diesel;
|
|
||||||
//! #[database("my_db")]
|
|
||||||
//! struct MyDatabase(diesel::SqliteConnection);
|
|
||||||
//!
|
|
||||||
//! #[get("/")]
|
|
||||||
//! fn my_handler(conn: MyDatabase) {
|
|
||||||
//! // ...
|
|
||||||
//! }
|
|
||||||
//! # }
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! A connection can be retrieved and used with the `run()` method:
|
|
||||||
//!
|
|
||||||
//! ```rust
|
|
||||||
//! # #[macro_use] extern crate rocket;
|
|
||||||
//! # #[macro_use] extern crate rocket_contrib;
|
|
||||||
//! #
|
|
||||||
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
|
||||||
//! # mod test {
|
|
||||||
//! # use rocket_contrib::databases::diesel;
|
|
||||||
//! # type Data = ();
|
|
||||||
//! #[database("my_db")]
|
|
||||||
//! struct MyDatabase(diesel::SqliteConnection);
|
|
||||||
//!
|
|
||||||
//! fn load_from_db(conn: &diesel::SqliteConnection) -> Data {
|
|
||||||
//! // Do something with connection, return some data.
|
|
||||||
//! # ()
|
|
||||||
//! }
|
|
||||||
//!
|
|
||||||
//! #[get("/")]
|
|
||||||
//! async fn my_handler(mut conn: MyDatabase) -> Data {
|
|
||||||
//! conn.run(|c| load_from_db(c)).await
|
|
||||||
//! }
|
|
||||||
//! # }
|
|
||||||
//! ```
|
|
||||||
//!
|
|
||||||
//! # Database Support
|
|
||||||
//!
|
|
||||||
//! Built-in support is provided for many popular databases and drivers. Support
|
|
||||||
//! can be easily extended by [`Poolable`] implementations.
|
|
||||||
//!
|
|
||||||
//! ## Provided
|
|
||||||
//!
|
|
||||||
//! The list below includes all presently supported database adapters and their
|
|
||||||
//! corresponding [`Poolable`] type.
|
|
||||||
//!
|
|
||||||
// Note: Keep this table in sync with site/guite/6-state.md
|
|
||||||
//! | Kind | Driver | Version | `Poolable` Type | Feature |
|
|
||||||
//! |----------|-----------------------|-----------|--------------------------------|------------------------|
|
|
||||||
//! | MySQL | [Diesel] | `1` | [`diesel::MysqlConnection`] | `diesel_mysql_pool` |
|
|
||||||
//! | MySQL | [`rust-mysql-simple`] | `18` | [`mysql::Conn`] | `mysql_pool` |
|
|
||||||
//! | Postgres | [Diesel] | `1` | [`diesel::PgConnection`] | `diesel_postgres_pool` |
|
|
||||||
//! | Postgres | [Rust-Postgres] | `0.19` | [`postgres::Client`] | `postgres_pool` |
|
|
||||||
//! | Sqlite | [Diesel] | `1` | [`diesel::SqliteConnection`] | `diesel_sqlite_pool` |
|
|
||||||
//! | Sqlite | [`Rusqlite`] | `0.23` | [`rusqlite::Connection`] | `sqlite_pool` |
|
|
||||||
//! | Memcache | [`memcache`] | `0.15` | [`memcache::Client`] | `memcache_pool` |
|
|
||||||
//!
|
|
||||||
//! [Diesel]: https://diesel.rs
|
|
||||||
//! [`rusqlite::Connection`]: https://docs.rs/rusqlite/0.23.0/rusqlite/struct.Connection.html
|
|
||||||
//! [`diesel::SqliteConnection`]: http://docs.diesel.rs/diesel/prelude/struct.SqliteConnection.html
|
|
||||||
//! [`postgres::Client`]: https://docs.rs/postgres/0.19/postgres/struct.Client.html
|
|
||||||
//! [`diesel::PgConnection`]: http://docs.diesel.rs/diesel/pg/struct.PgConnection.html
|
|
||||||
//! [`mysql::Conn`]: https://docs.rs/mysql/18/mysql/struct.Conn.html
|
|
||||||
//! [`diesel::MysqlConnection`]: http://docs.diesel.rs/diesel/mysql/struct.MysqlConnection.html
|
|
||||||
//! [`Rusqlite`]: https://github.com/jgallagher/rusqlite
|
|
||||||
//! [Rust-Postgres]: https://github.com/sfackler/rust-postgres
|
|
||||||
//! [`rust-mysql-simple`]: https://github.com/blackbeam/rust-mysql-simple
|
|
||||||
//! [`diesel::PgConnection`]: http://docs.diesel.rs/diesel/pg/struct.PgConnection.html
|
|
||||||
//! [`memcache`]: https://github.com/aisk/rust-memcache
|
|
||||||
//! [`memcache::Client`]: https://docs.rs/memcache/0.15/memcache/struct.Client.html
|
|
||||||
//!
|
|
||||||
//! The above table lists all the supported database adapters in this library.
|
|
||||||
//! In order to use particular `Poolable` type that's included in this library,
|
|
||||||
//! you must first enable the feature listed in the "Feature" column. The
|
|
||||||
//! interior type of your decorated database type should match the type in the
|
|
||||||
//! "`Poolable` Type" column.
|
|
||||||
//!
|
|
||||||
//! ## Extending
|
|
||||||
//!
|
|
||||||
//! Extending Rocket's support to your own custom database adapter (or other
|
|
||||||
//! database-like struct that can be pooled by `r2d2`) is as easy as
|
|
||||||
//! implementing the [`Poolable`] trait. See the documentation for [`Poolable`]
|
|
||||||
//! for more details on how to implement it.
|
|
||||||
//!
|
|
||||||
//! [`FromRequest`]: rocket::request::FromRequest
|
|
||||||
//! [request guards]: rocket::request::FromRequest
|
|
||||||
//! [`Poolable`]: crate::databases::Poolable
|
|
||||||
|
|
||||||
pub extern crate r2d2;
|
|
||||||
|
|
||||||
#[cfg(any(
|
|
||||||
feature = "diesel_sqlite_pool",
|
|
||||||
feature = "diesel_postgres_pool",
|
|
||||||
feature = "diesel_mysql_pool"
|
|
||||||
))]
|
|
||||||
pub extern crate diesel;
|
|
||||||
|
|
||||||
use std::marker::PhantomData;
|
|
||||||
use std::sync::Arc;
|
|
||||||
|
|
||||||
use rocket::fairing::{AdHoc, Fairing};
|
|
||||||
use rocket::request::{Request, Outcome, FromRequest};
|
|
||||||
use rocket::outcome::IntoOutcome;
|
|
||||||
use rocket::http::Status;
|
|
||||||
|
|
||||||
use rocket::tokio::sync::{OwnedSemaphorePermit, Semaphore, Mutex};
|
|
||||||
use rocket::tokio::time::timeout;
|
|
||||||
|
|
||||||
use self::r2d2::ManageConnection;
|
|
||||||
|
|
||||||
#[doc(hidden)] pub use rocket_contrib_codegen::*;
|
|
||||||
|
|
||||||
#[cfg(feature = "postgres_pool")] pub extern crate postgres;
|
|
||||||
#[cfg(feature = "postgres_pool")] pub extern crate r2d2_postgres;
|
|
||||||
|
|
||||||
#[cfg(feature = "mysql_pool")] pub extern crate mysql;
|
|
||||||
#[cfg(feature = "mysql_pool")] pub extern crate r2d2_mysql;
|
|
||||||
|
|
||||||
#[cfg(feature = "sqlite_pool")] pub extern crate rusqlite;
|
|
||||||
#[cfg(feature = "sqlite_pool")] pub extern crate r2d2_sqlite;
|
|
||||||
|
|
||||||
#[cfg(feature = "memcache_pool")] pub extern crate memcache;
|
|
||||||
#[cfg(feature = "memcache_pool")] pub extern crate r2d2_memcache;
|
|
||||||
|
|
||||||
/// A base `Config` for any `Poolable` type.
|
|
||||||
///
|
|
||||||
/// For the following configuration:
|
|
||||||
///
|
|
||||||
/// ```toml
|
|
||||||
/// [global.databases.my_database]
|
|
||||||
/// url = "postgres://root:root@localhost/my_database"
|
|
||||||
/// pool_size = 10
|
|
||||||
/// timeout = 5
|
|
||||||
/// ```
|
|
||||||
///
|
|
||||||
/// ...`Config::from("my_database", rocket)` would return the following struct:
|
|
||||||
///
|
|
||||||
/// ```rust
|
|
||||||
/// # use rocket_contrib::databases::Config;
|
|
||||||
/// Config {
|
|
||||||
/// url: "postgres://root:root@localhost/my_database".into(),
|
|
||||||
/// pool_size: 10,
|
|
||||||
/// timeout: 5
|
|
||||||
/// };
|
|
||||||
/// ```
|
|
||||||
///
|
|
||||||
/// If you want to implement your own custom database adapter (or other
|
|
||||||
/// database-like struct that can be pooled by `r2d2`) and need some more
|
|
||||||
/// configurations options, you may need to define a custom `Config` struct.
|
|
||||||
/// Note, however, that the configuration values in `Config` are required.
|
|
||||||
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
|
|
||||||
pub struct Config {
|
|
||||||
/// Connection URL specified in the Rocket configuration.
|
|
||||||
pub url: String,
|
|
||||||
/// Initial pool size. Defaults to the number of Rocket workers * 2.
|
|
||||||
pub pool_size: u32,
|
|
||||||
/// How long to wait, in seconds, for a new connection before timing out.
|
|
||||||
/// Defaults to `5`.
|
|
||||||
// FIXME: Use `time`.
|
|
||||||
pub timeout: u8,
|
|
||||||
}
|
|
||||||
|
|
||||||
use serde::{Serialize, Deserialize};
|
|
||||||
use rocket::figment::{self, Figment, providers::Serialized};
|
|
||||||
|
|
||||||
impl Config {
|
|
||||||
/// Retrieves the database configuration for the database named `name`.
|
|
||||||
///
|
|
||||||
/// This function is primarily used by the generated code from the
|
|
||||||
/// `#[database]` attribute.
|
|
||||||
///
|
|
||||||
/// # Example
|
|
||||||
///
|
|
||||||
/// ```rust
|
|
||||||
/// # #[cfg(feature = "diesel_sqlite_pool")] {
|
|
||||||
/// # use rocket::figment::{Figment, providers::{Format, Toml}};
|
|
||||||
/// // Assume that these are the contents of `Rocket.toml`:
|
|
||||||
/// # let toml = Toml::string(r#"
|
|
||||||
/// [global.databases]
|
|
||||||
/// my_db = { url = "db/db.sqlite", pool_size = 25 }
|
|
||||||
/// my_other_db = { url = "mysql://root:root@localhost/database" }
|
|
||||||
/// # "#).nested();
|
|
||||||
///
|
|
||||||
/// use rocket_contrib::databases::Config;
|
|
||||||
///
|
|
||||||
/// fn pool(rocket: &rocket::Rocket) {
|
|
||||||
/// let config = Config::from("my_db", rocket).unwrap();
|
|
||||||
/// assert_eq!(config.url, "db/db.sqlite");
|
|
||||||
/// assert_eq!(config.pool_size, 25);
|
|
||||||
///
|
|
||||||
/// let config = Config::from("my_other_db", rocket).unwrap();
|
|
||||||
/// assert_eq!(config.url, "mysql://root:root@localhost/database");
|
|
||||||
/// assert_eq!(config.pool_size, (rocket.config().workers * 2) as u32);
|
|
||||||
///
|
|
||||||
/// let config = Config::from("unknown_db", rocket);
|
|
||||||
/// assert!(config.is_err())
|
|
||||||
/// }
|
|
||||||
/// #
|
|
||||||
/// # let config = Figment::from(rocket::Config::default()).merge(toml);
|
|
||||||
/// # let rocket = rocket::custom(config);
|
|
||||||
/// # pool(&rocket);
|
|
||||||
/// # }
|
|
||||||
/// ```
|
|
||||||
pub fn from(db_name: &str, rocket: &rocket::Rocket) -> Result<Config, figment::Error> {
|
|
||||||
let db_key = format!("databases.{}", db_name);
|
|
||||||
let key = |name: &str| format!("{}.{}", db_key, name);
|
|
||||||
Figment::from(rocket.figment())
|
|
||||||
.merge(Serialized::default(&key("pool_size"), rocket.config().workers * 2))
|
|
||||||
.merge(Serialized::default(&key("timeout"), 5))
|
|
||||||
.extract_inner::<Self>(&db_key)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/// A wrapper around `r2d2::Error`s or a custom database error type.
|
|
||||||
///
|
|
||||||
/// This type is only relevant to implementors of the [`Poolable`] trait. See
|
|
||||||
/// the [`Poolable`] documentation for more information on how to use this type.
|
|
||||||
#[derive(Debug)]
|
|
||||||
pub enum Error<T> {
|
|
||||||
/// A custom error of type `T`.
|
|
||||||
Custom(T),
|
|
||||||
/// An error occurred while initializing an `r2d2` pool.
|
|
||||||
Pool(r2d2::Error),
|
|
||||||
/// An error occurred while extracting a `figment` configuration.
|
|
||||||
Config(figment::Error),
|
|
||||||
}
|
|
||||||
|
|
||||||
impl<T> From<figment::Error> for Error<T> {
|
|
||||||
fn from(error: figment::Error) -> Self {
|
|
||||||
Error::Config(error)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
impl<T> From<r2d2::Error> for Error<T> {
|
|
||||||
fn from(error: r2d2::Error) -> Self {
|
|
||||||
Error::Pool(error)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/// Trait implemented by `r2d2`-based database adapters.
|
|
||||||
///
|
|
||||||
/// # Provided Implementations
|
|
||||||
///
|
|
||||||
/// Implementations of `Poolable` are provided for the following types:
|
|
||||||
///
|
|
||||||
/// * `diesel::MysqlConnection`
|
|
||||||
/// * `diesel::PgConnection`
|
|
||||||
/// * `diesel::SqliteConnection`
|
|
||||||
/// * `postgres::Connection`
|
|
||||||
/// * `mysql::Conn`
|
|
||||||
/// * `rusqlite::Connection`
|
|
||||||
///
|
|
||||||
/// # Implementation Guide
|
|
||||||
///
|
|
||||||
/// As an r2d2-compatible database (or other resource) adapter provider,
|
|
||||||
/// implementing `Poolable` in your own library will enable Rocket users to
|
|
||||||
/// consume your adapter with its built-in connection pooling support.
|
|
||||||
///
|
|
||||||
/// ## Example
|
|
||||||
///
|
|
||||||
/// Consider a library `foo` with the following types:
|
|
||||||
///
|
|
||||||
/// * `foo::ConnectionManager`, which implements [`r2d2::ManageConnection`]
|
|
||||||
/// * `foo::Connection`, the `Connection` associated type of
|
|
||||||
/// `foo::ConnectionManager`
|
|
||||||
/// * `foo::Error`, errors resulting from manager instantiation
|
|
||||||
///
|
|
||||||
/// In order for Rocket to generate the required code to automatically provision
|
|
||||||
/// a r2d2 connection pool into application state, the `Poolable` trait needs to
|
|
||||||
/// be implemented for the connection type. The following example implements
|
|
||||||
/// `Poolable` for `foo::Connection`:
|
|
||||||
///
|
|
||||||
/// ```rust
|
|
||||||
/// # mod foo {
|
|
||||||
/// # use std::fmt;
|
|
||||||
/// # use rocket_contrib::databases::r2d2;
|
|
||||||
/// # #[derive(Debug)] pub struct Error;
|
|
||||||
/// # impl std::error::Error for Error { }
|
|
||||||
/// # impl fmt::Display for Error {
|
|
||||||
/// # fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { Ok(()) }
|
|
||||||
/// # }
|
|
||||||
/// #
|
|
||||||
/// # pub struct Connection;
|
|
||||||
/// # pub struct ConnectionManager;
|
|
||||||
/// #
|
|
||||||
/// # type Result<T> = std::result::Result<T, Error>;
|
|
||||||
/// #
|
|
||||||
/// # impl ConnectionManager {
|
|
||||||
/// # pub fn new(url: &str) -> Result<Self> { Err(Error) }
|
|
||||||
/// # }
|
|
||||||
/// #
|
|
||||||
/// # impl self::r2d2::ManageConnection for ConnectionManager {
|
|
||||||
/// # type Connection = Connection;
|
|
||||||
/// # type Error = Error;
|
|
||||||
/// # fn connect(&self) -> Result<Connection> { panic!(()) }
|
|
||||||
/// # fn is_valid(&self, _: &mut Connection) -> Result<()> { panic!() }
|
|
||||||
/// # fn has_broken(&self, _: &mut Connection) -> bool { panic!() }
|
|
||||||
/// # }
|
|
||||||
/// # }
|
|
||||||
/// use rocket_contrib::databases::{r2d2, Error, Config, Poolable, PoolResult};
|
|
||||||
///
|
|
||||||
/// impl Poolable for foo::Connection {
|
|
||||||
/// type Manager = foo::ConnectionManager;
|
|
||||||
/// type Error = foo::Error;
|
|
||||||
///
|
|
||||||
/// fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
|
||||||
/// let config = Config::from(db_name, rocket)?;
|
|
||||||
/// let manager = foo::ConnectionManager::new(&config.url).map_err(Error::Custom)?;
|
|
||||||
/// Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
|
||||||
/// }
|
|
||||||
/// }
|
|
||||||
/// ```
|
|
||||||
///
|
|
||||||
/// In this example, `ConnectionManager::new()` method returns a `foo::Error` on
|
|
||||||
/// failure. The [`Error`] enum consolidates this type, the `r2d2::Error` type
|
|
||||||
/// that can result from `r2d2::Pool::builder()`, and the
|
|
||||||
/// [`figment::Error`](rocket::figment::Error) type from
|
|
||||||
/// `database::Config::from()`.
|
|
||||||
///
|
|
||||||
/// In the event that a connection manager isn't fallible (as is the case with
|
|
||||||
/// Diesel's r2d2 connection manager, for instance), the associated error type
|
|
||||||
/// for the `Poolable` implementation should be `std::convert::Infallible`.
|
|
||||||
///
|
|
||||||
/// For more concrete example, consult Rocket's existing implementations of
|
|
||||||
/// [`Poolable`].
|
|
||||||
pub trait Poolable: Send + Sized + 'static {
|
|
||||||
/// The associated connection manager for the given connection type.
|
|
||||||
type Manager: ManageConnection<Connection=Self>;
|
|
||||||
|
|
||||||
/// The associated error type in the event that constructing the connection
|
|
||||||
/// manager and/or the connection pool fails.
|
|
||||||
type Error: std::fmt::Debug;
|
|
||||||
|
|
||||||
/// Creates an `r2d2` connection pool for `Manager::Connection`, returning
|
|
||||||
/// the pool on success.
|
|
||||||
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self>;
|
|
||||||
}
|
|
||||||
|
|
||||||
/// A type alias for the return type of [`Poolable::pool()`].
|
|
||||||
#[allow(type_alias_bounds)]
|
|
||||||
pub type PoolResult<P: Poolable> = Result<r2d2::Pool<P::Manager>, Error<P::Error>>;
|
|
||||||
|
|
||||||
#[cfg(feature = "diesel_sqlite_pool")]
|
|
||||||
impl Poolable for diesel::SqliteConnection {
|
|
||||||
type Manager = diesel::r2d2::ConnectionManager<diesel::SqliteConnection>;
|
|
||||||
type Error = std::convert::Infallible;
|
|
||||||
|
|
||||||
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
|
||||||
let config = Config::from(db_name, rocket)?;
|
|
||||||
let manager = diesel::r2d2::ConnectionManager::new(&config.url);
|
|
||||||
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
#[cfg(feature = "diesel_postgres_pool")]
|
|
||||||
impl Poolable for diesel::PgConnection {
|
|
||||||
type Manager = diesel::r2d2::ConnectionManager<diesel::PgConnection>;
|
|
||||||
type Error = std::convert::Infallible;
|
|
||||||
|
|
||||||
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
|
||||||
let config = Config::from(db_name, rocket)?;
|
|
||||||
let manager = diesel::r2d2::ConnectionManager::new(&config.url);
|
|
||||||
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
#[cfg(feature = "diesel_mysql_pool")]
|
|
||||||
impl Poolable for diesel::MysqlConnection {
|
|
||||||
type Manager = diesel::r2d2::ConnectionManager<diesel::MysqlConnection>;
|
|
||||||
type Error = std::convert::Infallible;
|
|
||||||
|
|
||||||
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
|
||||||
let config = Config::from(db_name, rocket)?;
|
|
||||||
let manager = diesel::r2d2::ConnectionManager::new(&config.url);
|
|
||||||
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// TODO: Add a feature to enable TLS in `postgres`; parse a suitable `config`.
|
|
||||||
#[cfg(feature = "postgres_pool")]
|
|
||||||
impl Poolable for postgres::Client {
|
|
||||||
type Manager = r2d2_postgres::PostgresConnectionManager<postgres::tls::NoTls>;
|
|
||||||
type Error = postgres::Error;
|
|
||||||
|
|
||||||
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
|
||||||
let config = Config::from(db_name, rocket)?;
|
|
||||||
let url = config.url.parse().map_err(Error::Custom)?;
|
|
||||||
let manager = r2d2_postgres::PostgresConnectionManager::new(url, postgres::tls::NoTls);
|
|
||||||
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
#[cfg(feature = "mysql_pool")]
|
|
||||||
impl Poolable for mysql::Conn {
|
|
||||||
type Manager = r2d2_mysql::MysqlConnectionManager;
|
|
||||||
type Error = std::convert::Infallible;
|
|
||||||
|
|
||||||
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
|
||||||
let config = Config::from(db_name, rocket)?;
|
|
||||||
let opts = mysql::OptsBuilder::from_opts(&config.url);
|
|
||||||
let manager = r2d2_mysql::MysqlConnectionManager::new(opts);
|
|
||||||
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
#[cfg(feature = "sqlite_pool")]
|
|
||||||
impl Poolable for rusqlite::Connection {
|
|
||||||
type Manager = r2d2_sqlite::SqliteConnectionManager;
|
|
||||||
type Error = std::convert::Infallible;
|
|
||||||
|
|
||||||
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
|
||||||
let config = Config::from(db_name, rocket)?;
|
|
||||||
let manager = r2d2_sqlite::SqliteConnectionManager::file(&*config.url);
|
|
||||||
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
#[cfg(feature = "memcache_pool")]
|
|
||||||
impl Poolable for memcache::Client {
|
|
||||||
type Manager = r2d2_memcache::MemcacheConnectionManager;
|
|
||||||
// Unused, but we might want it in the future without a breaking change.
|
|
||||||
type Error = memcache::MemcacheError;
|
|
||||||
|
|
||||||
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
|
||||||
let config = Config::from(db_name, rocket)?;
|
|
||||||
let manager = r2d2_memcache::MemcacheConnectionManager::new(&*config.url);
|
|
||||||
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/// Unstable internal details of generated code for the #[database] attribute.
|
|
||||||
///
|
|
||||||
/// This type is implemented here instead of in generated code to ensure all
|
|
||||||
/// types are properly checked.
|
|
||||||
#[doc(hidden)]
|
|
||||||
pub struct ConnectionPool<K, C: Poolable> {
|
|
||||||
config: Config,
|
|
||||||
// This is an 'Option' so that we can drop the pool in a 'spawn_blocking'.
|
|
||||||
pool: Option<r2d2::Pool<C::Manager>>,
|
|
||||||
semaphore: Arc<Semaphore>,
|
|
||||||
_marker: PhantomData<fn() -> K>,
|
|
||||||
}
|
|
||||||
|
|
||||||
impl<K, C: Poolable> Clone for ConnectionPool<K, C> {
|
|
||||||
fn clone(&self) -> Self {
|
|
||||||
ConnectionPool {
|
|
||||||
config: self.config.clone(),
|
|
||||||
pool: self.pool.clone(),
|
|
||||||
semaphore: self.semaphore.clone(),
|
|
||||||
_marker: PhantomData
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/// Unstable internal details of generated code for the #[database] attribute.
|
|
||||||
///
|
|
||||||
/// This type is implemented here instead of in generated code to ensure all
|
|
||||||
/// types are properly checked.
|
|
||||||
#[doc(hidden)]
|
|
||||||
pub struct Connection<K, C: Poolable> {
|
|
||||||
connection: Arc<Mutex<Option<r2d2::PooledConnection<C::Manager>>>>,
|
|
||||||
permit: Option<OwnedSemaphorePermit>,
|
|
||||||
_marker: PhantomData<fn() -> K>,
|
|
||||||
}
|
|
||||||
|
|
||||||
// A wrapper around spawn_blocking that propagates panics to the calling code.
|
|
||||||
async fn run_blocking<F, R>(job: F) -> R
|
|
||||||
where F: FnOnce() -> R + Send + 'static, R: Send + 'static,
|
|
||||||
{
|
|
||||||
match tokio::task::spawn_blocking(job).await {
|
|
||||||
Ok(ret) => ret,
|
|
||||||
Err(e) => match e.try_into_panic() {
|
|
||||||
Ok(panic) => std::panic::resume_unwind(panic),
|
|
||||||
Err(_) => unreachable!("spawn_blocking tasks are never cancelled"),
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
macro_rules! dberr {
|
|
||||||
($msg:literal, $db_name:expr, $efmt:literal, $error:expr, $rocket:expr) => ({
|
|
||||||
rocket::error!(concat!("database ", $msg, " error for pool named `{}`"), $db_name);
|
|
||||||
error_!($efmt, $error);
|
|
||||||
return Err($rocket);
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
impl<K: 'static, C: Poolable> ConnectionPool<K, C> {
|
|
||||||
pub fn fairing(fairing_name: &'static str, db: &'static str) -> impl Fairing {
|
|
||||||
AdHoc::on_attach(fairing_name, move |rocket| async move {
|
|
||||||
let config = match Config::from(db, &rocket) {
|
|
||||||
Ok(config) => config,
|
|
||||||
Err(e) => dberr!("config", db, "{}", e, rocket),
|
|
||||||
};
|
|
||||||
|
|
||||||
let pool_size = config.pool_size;
|
|
||||||
match C::pool(db, &rocket) {
|
|
||||||
Ok(pool) => Ok(rocket.manage(ConnectionPool::<K, C> {
|
|
||||||
config,
|
|
||||||
pool: Some(pool),
|
|
||||||
semaphore: Arc::new(Semaphore::new(pool_size as usize)),
|
|
||||||
_marker: PhantomData,
|
|
||||||
})),
|
|
||||||
Err(Error::Config(e)) => dberr!("config", db, "{}", e, rocket),
|
|
||||||
Err(Error::Pool(e)) => dberr!("pool init", db, "{}", e, rocket),
|
|
||||||
Err(Error::Custom(e)) => dberr!("pool manager", db, "{:?}", e, rocket),
|
|
||||||
}
|
|
||||||
})
|
|
||||||
}
|
|
||||||
|
|
||||||
async fn get(&self) -> Result<Connection<K, C>, ()> {
|
|
||||||
let duration = std::time::Duration::from_secs(self.config.timeout as u64);
|
|
||||||
let permit = match timeout(duration, self.semaphore.clone().acquire_owned()).await {
|
|
||||||
Ok(p) => p.expect("internal invariant broken: semaphore should not be closed"),
|
|
||||||
Err(_) => {
|
|
||||||
error_!("database connection retrieval timed out");
|
|
||||||
return Err(());
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
let pool = self.pool.as_ref().cloned()
|
|
||||||
.expect("internal invariant broken: self.pool is Some");
|
|
||||||
|
|
||||||
match run_blocking(move || pool.get_timeout(duration)).await {
|
|
||||||
Ok(c) => Ok(Connection {
|
|
||||||
connection: Arc::new(Mutex::new(Some(c))),
|
|
||||||
permit: Some(permit),
|
|
||||||
_marker: PhantomData,
|
|
||||||
}),
|
|
||||||
Err(e) => {
|
|
||||||
error_!("failed to get a database connection: {}", e);
|
|
||||||
Err(())
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
#[inline]
|
|
||||||
pub async fn get_one(rocket: &rocket::Rocket) -> Option<Connection<K, C>> {
|
|
||||||
match rocket.state::<Self>() {
|
|
||||||
Some(pool) => pool.get().await.ok(),
|
|
||||||
None => None
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
#[inline]
|
|
||||||
pub async fn get_pool(rocket: &rocket::Rocket) -> Option<Self> {
|
|
||||||
rocket.state::<Self>().map(|pool| pool.clone())
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
impl<K: 'static, C: Poolable> Connection<K, C> {
|
|
||||||
#[inline]
|
|
||||||
pub async fn run<F, R>(&self, f: F) -> R
|
|
||||||
where F: FnOnce(&mut C) -> R + Send + 'static,
|
|
||||||
R: Send + 'static,
|
|
||||||
{
|
|
||||||
let mut connection = self.connection.clone().lock_owned().await;
|
|
||||||
run_blocking(move || {
|
|
||||||
let conn = connection.as_mut()
|
|
||||||
.expect("internal invariant broken: self.connection is Some");
|
|
||||||
f(conn)
|
|
||||||
}).await
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
impl<K, C: Poolable> Drop for Connection<K, C> {
|
|
||||||
fn drop(&mut self) {
|
|
||||||
let connection = self.connection.clone();
|
|
||||||
let permit = self.permit.take();
|
|
||||||
tokio::spawn(async move {
|
|
||||||
let mut connection = connection.lock_owned().await;
|
|
||||||
tokio::task::spawn_blocking(move || {
|
|
||||||
if let Some(conn) = connection.take() {
|
|
||||||
drop(conn);
|
|
||||||
}
|
|
||||||
|
|
||||||
// Explicitly dropping the permit here so that it's only
|
|
||||||
// released after the connection is.
|
|
||||||
drop(permit);
|
|
||||||
})
|
|
||||||
});
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
impl<K, C: Poolable> Drop for ConnectionPool<K, C> {
|
|
||||||
fn drop(&mut self) {
|
|
||||||
let pool = self.pool.take();
|
|
||||||
tokio::task::spawn_blocking(move || drop(pool));
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
#[rocket::async_trait]
|
|
||||||
impl<'a, 'r, K: 'static, C: Poolable> FromRequest<'a, 'r> for Connection<K, C> {
|
|
||||||
type Error = ();
|
|
||||||
|
|
||||||
#[inline]
|
|
||||||
async fn from_request(request: &'a Request<'r>) -> Outcome<Self, ()> {
|
|
||||||
match request.managed_state::<ConnectionPool<K, C>>() {
|
|
||||||
Some(c) => c.get().await.into_outcome(Status::ServiceUnavailable),
|
|
||||||
None => {
|
|
||||||
error_!("Missing database fairing for `{}`", std::any::type_name::<K>());
|
|
||||||
Outcome::Failure((Status::InternalServerError, ()))
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
@ -0,0 +1,89 @@
|
||||||
|
/// A base `Config` for any `Poolable` type.
|
||||||
|
///
|
||||||
|
/// For the following configuration:
|
||||||
|
///
|
||||||
|
/// ```toml
|
||||||
|
/// [global.databases.my_database]
|
||||||
|
/// url = "postgres://root:root@localhost/my_database"
|
||||||
|
/// pool_size = 10
|
||||||
|
/// timeout = 5
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// ...`Config::from("my_database", rocket)` would return the following struct:
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// # use rocket_contrib::databases::Config;
|
||||||
|
/// Config {
|
||||||
|
/// url: "postgres://root:root@localhost/my_database".into(),
|
||||||
|
/// pool_size: 10,
|
||||||
|
/// timeout: 5
|
||||||
|
/// };
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// If you want to implement your own custom database adapter (or other
|
||||||
|
/// database-like struct that can be pooled by `r2d2`) and need some more
|
||||||
|
/// configurations options, you may need to define a custom `Config` struct.
|
||||||
|
/// Note, however, that the configuration values in `Config` are required.
|
||||||
|
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
|
||||||
|
pub struct Config {
|
||||||
|
/// Connection URL specified in the Rocket configuration.
|
||||||
|
pub url: String,
|
||||||
|
/// Initial pool size. Defaults to the number of Rocket workers * 2.
|
||||||
|
pub pool_size: u32,
|
||||||
|
/// How long to wait, in seconds, for a new connection before timing out.
|
||||||
|
/// Defaults to `5`.
|
||||||
|
// FIXME: Use `time`.
|
||||||
|
pub timeout: u8,
|
||||||
|
}
|
||||||
|
|
||||||
|
use serde::{Serialize, Deserialize};
|
||||||
|
use rocket::figment::{self, Figment, providers::Serialized};
|
||||||
|
|
||||||
|
impl Config {
|
||||||
|
/// Retrieves the database configuration for the database named `name`.
|
||||||
|
///
|
||||||
|
/// This function is primarily used by the generated code from the
|
||||||
|
/// `#[database]` attribute.
|
||||||
|
///
|
||||||
|
/// # Example
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// # #[cfg(feature = "diesel_sqlite_pool")] {
|
||||||
|
/// # use rocket::figment::{Figment, providers::{Format, Toml}};
|
||||||
|
/// // Assume that these are the contents of `Rocket.toml`:
|
||||||
|
/// # let toml = Toml::string(r#"
|
||||||
|
/// [global.databases]
|
||||||
|
/// my_db = { url = "db/db.sqlite", pool_size = 25 }
|
||||||
|
/// my_other_db = { url = "mysql://root:root@localhost/database" }
|
||||||
|
/// # "#).nested();
|
||||||
|
///
|
||||||
|
/// use rocket_contrib::databases::Config;
|
||||||
|
///
|
||||||
|
/// fn pool(rocket: &rocket::Rocket) {
|
||||||
|
/// let config = Config::from("my_db", rocket).unwrap();
|
||||||
|
/// assert_eq!(config.url, "db/db.sqlite");
|
||||||
|
/// assert_eq!(config.pool_size, 25);
|
||||||
|
///
|
||||||
|
/// let config = Config::from("my_other_db", rocket).unwrap();
|
||||||
|
/// assert_eq!(config.url, "mysql://root:root@localhost/database");
|
||||||
|
/// assert_eq!(config.pool_size, (rocket.config().workers * 2) as u32);
|
||||||
|
///
|
||||||
|
/// let config = Config::from("unknown_db", rocket);
|
||||||
|
/// assert!(config.is_err())
|
||||||
|
/// }
|
||||||
|
/// #
|
||||||
|
/// # let config = Figment::from(rocket::Config::default()).merge(toml);
|
||||||
|
/// # let rocket = rocket::custom(config);
|
||||||
|
/// # pool(&rocket);
|
||||||
|
/// # }
|
||||||
|
/// ```
|
||||||
|
pub fn from(db_name: &str, rocket: &rocket::Rocket) -> Result<Config, figment::Error> {
|
||||||
|
let db_key = format!("databases.{}", db_name);
|
||||||
|
let key = |name: &str| format!("{}.{}", db_key, name);
|
||||||
|
Figment::from(rocket.figment())
|
||||||
|
.merge(Serialized::default(&key("pool_size"), rocket.config().workers * 2))
|
||||||
|
.merge(Serialized::default(&key("timeout"), 5))
|
||||||
|
.extract_inner::<Self>(&db_key)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
@ -0,0 +1,188 @@
|
||||||
|
use std::marker::PhantomData;
|
||||||
|
use std::sync::Arc;
|
||||||
|
|
||||||
|
use rocket::fairing::{AdHoc, Fairing};
|
||||||
|
use rocket::request::{Request, Outcome, FromRequest};
|
||||||
|
use rocket::outcome::IntoOutcome;
|
||||||
|
use rocket::http::Status;
|
||||||
|
|
||||||
|
use rocket::tokio::sync::{OwnedSemaphorePermit, Semaphore, Mutex};
|
||||||
|
use rocket::tokio::time::timeout;
|
||||||
|
|
||||||
|
use crate::databases::{Config, Poolable, Error};
|
||||||
|
|
||||||
|
/// Unstable internal details of generated code for the #[database] attribute.
|
||||||
|
///
|
||||||
|
/// This type is implemented here instead of in generated code to ensure all
|
||||||
|
/// types are properly checked.
|
||||||
|
#[doc(hidden)]
|
||||||
|
pub struct ConnectionPool<K, C: Poolable> {
|
||||||
|
config: Config,
|
||||||
|
// This is an 'Option' so that we can drop the pool in a 'spawn_blocking'.
|
||||||
|
pool: Option<r2d2::Pool<C::Manager>>,
|
||||||
|
semaphore: Arc<Semaphore>,
|
||||||
|
_marker: PhantomData<fn() -> K>,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<K, C: Poolable> Clone for ConnectionPool<K, C> {
|
||||||
|
fn clone(&self) -> Self {
|
||||||
|
ConnectionPool {
|
||||||
|
config: self.config.clone(),
|
||||||
|
pool: self.pool.clone(),
|
||||||
|
semaphore: self.semaphore.clone(),
|
||||||
|
_marker: PhantomData
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Unstable internal details of generated code for the #[database] attribute.
|
||||||
|
///
|
||||||
|
/// This type is implemented here instead of in generated code to ensure all
|
||||||
|
/// types are properly checked.
|
||||||
|
#[doc(hidden)]
|
||||||
|
pub struct Connection<K, C: Poolable> {
|
||||||
|
connection: Arc<Mutex<Option<r2d2::PooledConnection<C::Manager>>>>,
|
||||||
|
permit: Option<OwnedSemaphorePermit>,
|
||||||
|
_marker: PhantomData<fn() -> K>,
|
||||||
|
}
|
||||||
|
|
||||||
|
// A wrapper around spawn_blocking that propagates panics to the calling code.
|
||||||
|
async fn run_blocking<F, R>(job: F) -> R
|
||||||
|
where F: FnOnce() -> R + Send + 'static, R: Send + 'static,
|
||||||
|
{
|
||||||
|
match tokio::task::spawn_blocking(job).await {
|
||||||
|
Ok(ret) => ret,
|
||||||
|
Err(e) => match e.try_into_panic() {
|
||||||
|
Ok(panic) => std::panic::resume_unwind(panic),
|
||||||
|
Err(_) => unreachable!("spawn_blocking tasks are never cancelled"),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
macro_rules! dberr {
|
||||||
|
($msg:literal, $db_name:expr, $efmt:literal, $error:expr, $rocket:expr) => ({
|
||||||
|
rocket::error!(concat!("database ", $msg, " error for pool named `{}`"), $db_name);
|
||||||
|
error_!($efmt, $error);
|
||||||
|
return Err($rocket);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<K: 'static, C: Poolable> ConnectionPool<K, C> {
|
||||||
|
pub fn fairing(fairing_name: &'static str, db: &'static str) -> impl Fairing {
|
||||||
|
AdHoc::on_attach(fairing_name, move |rocket| async move {
|
||||||
|
let config = match Config::from(db, &rocket) {
|
||||||
|
Ok(config) => config,
|
||||||
|
Err(e) => dberr!("config", db, "{}", e, rocket),
|
||||||
|
};
|
||||||
|
|
||||||
|
let pool_size = config.pool_size;
|
||||||
|
match C::pool(db, &rocket) {
|
||||||
|
Ok(pool) => Ok(rocket.manage(ConnectionPool::<K, C> {
|
||||||
|
config,
|
||||||
|
pool: Some(pool),
|
||||||
|
semaphore: Arc::new(Semaphore::new(pool_size as usize)),
|
||||||
|
_marker: PhantomData,
|
||||||
|
})),
|
||||||
|
Err(Error::Config(e)) => dberr!("config", db, "{}", e, rocket),
|
||||||
|
Err(Error::Pool(e)) => dberr!("pool init", db, "{}", e, rocket),
|
||||||
|
Err(Error::Custom(e)) => dberr!("pool manager", db, "{:?}", e, rocket),
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn get(&self) -> Result<Connection<K, C>, ()> {
|
||||||
|
let duration = std::time::Duration::from_secs(self.config.timeout as u64);
|
||||||
|
let permit = match timeout(duration, self.semaphore.clone().acquire_owned()).await {
|
||||||
|
Ok(p) => p.expect("internal invariant broken: semaphore should not be closed"),
|
||||||
|
Err(_) => {
|
||||||
|
error_!("database connection retrieval timed out");
|
||||||
|
return Err(());
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
let pool = self.pool.as_ref().cloned()
|
||||||
|
.expect("internal invariant broken: self.pool is Some");
|
||||||
|
|
||||||
|
match run_blocking(move || pool.get_timeout(duration)).await {
|
||||||
|
Ok(c) => Ok(Connection {
|
||||||
|
connection: Arc::new(Mutex::new(Some(c))),
|
||||||
|
permit: Some(permit),
|
||||||
|
_marker: PhantomData,
|
||||||
|
}),
|
||||||
|
Err(e) => {
|
||||||
|
error_!("failed to get a database connection: {}", e);
|
||||||
|
Err(())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[inline]
|
||||||
|
pub async fn get_one(rocket: &rocket::Rocket) -> Option<Connection<K, C>> {
|
||||||
|
match rocket.state::<Self>() {
|
||||||
|
Some(pool) => pool.get().await.ok(),
|
||||||
|
None => None
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[inline]
|
||||||
|
pub async fn get_pool(rocket: &rocket::Rocket) -> Option<Self> {
|
||||||
|
rocket.state::<Self>().map(|pool| pool.clone())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<K: 'static, C: Poolable> Connection<K, C> {
|
||||||
|
#[inline]
|
||||||
|
pub async fn run<F, R>(&self, f: F) -> R
|
||||||
|
where F: FnOnce(&mut C) -> R + Send + 'static,
|
||||||
|
R: Send + 'static,
|
||||||
|
{
|
||||||
|
let mut connection = self.connection.clone().lock_owned().await;
|
||||||
|
run_blocking(move || {
|
||||||
|
let conn = connection.as_mut()
|
||||||
|
.expect("internal invariant broken: self.connection is Some");
|
||||||
|
f(conn)
|
||||||
|
}).await
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<K, C: Poolable> Drop for Connection<K, C> {
|
||||||
|
fn drop(&mut self) {
|
||||||
|
let connection = self.connection.clone();
|
||||||
|
let permit = self.permit.take();
|
||||||
|
tokio::spawn(async move {
|
||||||
|
let mut connection = connection.lock_owned().await;
|
||||||
|
tokio::task::spawn_blocking(move || {
|
||||||
|
if let Some(conn) = connection.take() {
|
||||||
|
drop(conn);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Explicitly dropping the permit here so that it's only
|
||||||
|
// released after the connection is.
|
||||||
|
drop(permit);
|
||||||
|
})
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<K, C: Poolable> Drop for ConnectionPool<K, C> {
|
||||||
|
fn drop(&mut self) {
|
||||||
|
let pool = self.pool.take();
|
||||||
|
tokio::task::spawn_blocking(move || drop(pool));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[rocket::async_trait]
|
||||||
|
impl<'a, 'r, K: 'static, C: Poolable> FromRequest<'a, 'r> for Connection<K, C> {
|
||||||
|
type Error = ();
|
||||||
|
|
||||||
|
#[inline]
|
||||||
|
async fn from_request(request: &'a Request<'r>) -> Outcome<Self, ()> {
|
||||||
|
match request.managed_state::<ConnectionPool<K, C>>() {
|
||||||
|
Some(c) => c.get().await.into_outcome(Status::ServiceUnavailable),
|
||||||
|
None => {
|
||||||
|
error_!("Missing database fairing for `{}`", std::any::type_name::<K>());
|
||||||
|
Outcome::Failure((Status::InternalServerError, ()))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,27 @@
|
||||||
|
use rocket::figment;
|
||||||
|
|
||||||
|
/// A wrapper around `r2d2::Error`s or a custom database error type.
|
||||||
|
///
|
||||||
|
/// This type is only relevant to implementors of the [`Poolable`] trait. See
|
||||||
|
/// the [`Poolable`] documentation for more information on how to use this type.
|
||||||
|
#[derive(Debug)]
|
||||||
|
pub enum Error<T> {
|
||||||
|
/// A custom error of type `T`.
|
||||||
|
Custom(T),
|
||||||
|
/// An error occurred while initializing an `r2d2` pool.
|
||||||
|
Pool(r2d2::Error),
|
||||||
|
/// An error occurred while extracting a `figment` configuration.
|
||||||
|
Config(figment::Error),
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<T> From<figment::Error> for Error<T> {
|
||||||
|
fn from(error: figment::Error) -> Self {
|
||||||
|
Error::Config(error)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl<T> From<r2d2::Error> for Error<T> {
|
||||||
|
fn from(error: r2d2::Error) -> Self {
|
||||||
|
Error::Pool(error)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,395 @@
|
||||||
|
//! Traits, utilities, and a macro for easy database connection pooling.
|
||||||
|
//!
|
||||||
|
//! # Overview
|
||||||
|
//!
|
||||||
|
//! This module provides traits, utilities, and a procedural macro that allows
|
||||||
|
//! you to easily connect your Rocket application to databases through
|
||||||
|
//! connection pools. A _database connection pool_ is a data structure that
|
||||||
|
//! maintains active database connections for later use in the application.
|
||||||
|
//! This implementation of connection pooling support is based on
|
||||||
|
//! [`r2d2`] and exposes connections through [request guards]. Databases are
|
||||||
|
//! individually configured through Rocket's regular configuration mechanisms: a
|
||||||
|
//! `Rocket.toml` file, environment variables, or procedurally.
|
||||||
|
//!
|
||||||
|
//! Connecting your Rocket application to a database using this library occurs
|
||||||
|
//! in three simple steps:
|
||||||
|
//!
|
||||||
|
//! 1. Configure your databases in `Rocket.toml`.
|
||||||
|
//! (see [Configuration](#configuration))
|
||||||
|
//! 2. Associate a request guard type and fairing with each database.
|
||||||
|
//! (see [Guard Types](#guard-types))
|
||||||
|
//! 3. Use the request guard to retrieve a connection in a handler.
|
||||||
|
//! (see [Handlers](#handlers))
|
||||||
|
//!
|
||||||
|
//! For a list of supported databases, see [Provided Databases](#provided). This
|
||||||
|
//! support can be easily extended by implementing the [`Poolable`] trait. See
|
||||||
|
//! [Extending](#extending) for more.
|
||||||
|
//!
|
||||||
|
//! ## Example
|
||||||
|
//!
|
||||||
|
//! Before using this library, the feature corresponding to your database type
|
||||||
|
//! in `rocket_contrib` must be enabled:
|
||||||
|
//!
|
||||||
|
//! ```toml
|
||||||
|
//! [dependencies.rocket_contrib]
|
||||||
|
//! version = "0.5.0-dev"
|
||||||
|
//! default-features = false
|
||||||
|
//! features = ["diesel_sqlite_pool"]
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! See [Provided](#provided) for a list of supported database and their
|
||||||
|
//! associated feature name.
|
||||||
|
//!
|
||||||
|
//! In whichever configuration source you choose, configure a `databases`
|
||||||
|
//! dictionary with an internal dictionary for each database, here `sqlite_logs`
|
||||||
|
//! in a TOML source:
|
||||||
|
//!
|
||||||
|
//! ```toml
|
||||||
|
//! [global.databases]
|
||||||
|
//! sqlite_logs = { url = "/path/to/database.sqlite" }
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! In your application's source code, one-time:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! #[macro_use] extern crate rocket;
|
||||||
|
//! #[macro_use] extern crate rocket_contrib;
|
||||||
|
//!
|
||||||
|
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
||||||
|
//! # mod test {
|
||||||
|
//! use rocket_contrib::databases::diesel;
|
||||||
|
//!
|
||||||
|
//! #[database("sqlite_logs")]
|
||||||
|
//! struct LogsDbConn(diesel::SqliteConnection);
|
||||||
|
//!
|
||||||
|
//! #[launch]
|
||||||
|
//! fn rocket() -> rocket::Rocket {
|
||||||
|
//! rocket::ignite().attach(LogsDbConn::fairing())
|
||||||
|
//! }
|
||||||
|
//! # } fn main() {}
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! Whenever a connection to the database is needed:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! # #[macro_use] extern crate rocket;
|
||||||
|
//! # #[macro_use] extern crate rocket_contrib;
|
||||||
|
//! #
|
||||||
|
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
||||||
|
//! # mod test {
|
||||||
|
//! # use rocket_contrib::databases::diesel;
|
||||||
|
//! #
|
||||||
|
//! # #[database("sqlite_logs")]
|
||||||
|
//! # struct LogsDbConn(diesel::SqliteConnection);
|
||||||
|
//! #
|
||||||
|
//! # type Logs = ();
|
||||||
|
//! # type Result<T> = std::result::Result<T, ()>;
|
||||||
|
//! #
|
||||||
|
//! #[get("/logs/<id>")]
|
||||||
|
//! async fn get_logs(conn: LogsDbConn, id: usize) -> Result<Logs> {
|
||||||
|
//! # /*
|
||||||
|
//! conn.run(|c| Logs::by_id(c, id)).await
|
||||||
|
//! # */
|
||||||
|
//! # Ok(())
|
||||||
|
//! }
|
||||||
|
//! # } fn main() {}
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! # Usage
|
||||||
|
//!
|
||||||
|
//! ## Configuration
|
||||||
|
//!
|
||||||
|
//! Databases can be configured as any other values. Using the default
|
||||||
|
//! configuration provider, either via `Rocket.toml` or environment variables.
|
||||||
|
//! You can also use a custom provider.
|
||||||
|
//!
|
||||||
|
//! ### `Rocket.toml`
|
||||||
|
//!
|
||||||
|
//! To configure a database via `Rocket.toml`, add a table for each database
|
||||||
|
//! to the `databases` table where the key is a name of your choice. The table
|
||||||
|
//! should have a `url` key and, optionally, a `pool_size` key. This looks as
|
||||||
|
//! follows:
|
||||||
|
//!
|
||||||
|
//! ```toml
|
||||||
|
//! # Option 1:
|
||||||
|
//! [global.databases]
|
||||||
|
//! sqlite_db = { url = "db.sqlite" }
|
||||||
|
//!
|
||||||
|
//! # Option 2:
|
||||||
|
//! [global.databases.my_db]
|
||||||
|
//! url = "mysql://root:root@localhost/my_db"
|
||||||
|
//!
|
||||||
|
//! # With a `pool_size` key:
|
||||||
|
//! [global.databases]
|
||||||
|
//! sqlite_db = { url = "db.sqlite", pool_size = 20 }
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! The table _requires_ one key:
|
||||||
|
//!
|
||||||
|
//! * `url` - the URl to the database
|
||||||
|
//!
|
||||||
|
//! Additionally, all configurations accept the following _optional_ keys:
|
||||||
|
//!
|
||||||
|
//! * `pool_size` - the size of the pool, i.e., the number of connections to
|
||||||
|
//! pool (defaults to the configured number of workers * 2)
|
||||||
|
//!
|
||||||
|
//! Additional options may be required or supported by other adapters.
|
||||||
|
//!
|
||||||
|
//! ### Procedurally
|
||||||
|
//!
|
||||||
|
//! Databases can also be configured procedurally via `rocket::custom()`.
|
||||||
|
//! The example below does just this:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! # #[cfg(feature = "diesel_sqlite_pool")] {
|
||||||
|
//! use rocket::figment::{value::{Map, Value}, util::map};
|
||||||
|
//!
|
||||||
|
//! #[rocket::launch]
|
||||||
|
//! fn rocket() -> _ {
|
||||||
|
//! let db: Map<_, Value> = map! {
|
||||||
|
//! "url" => "db.sqlite".into(),
|
||||||
|
//! "pool_size" => 10.into()
|
||||||
|
//! };
|
||||||
|
//!
|
||||||
|
//! let figment = rocket::Config::figment()
|
||||||
|
//! .merge(("databases", map!["my_db" => db]));
|
||||||
|
//!
|
||||||
|
//! rocket::custom(figment)
|
||||||
|
//! }
|
||||||
|
//! # rocket();
|
||||||
|
//! # }
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! ### Environment Variables
|
||||||
|
//!
|
||||||
|
//! Lastly, databases can be configured via environment variables by specifying
|
||||||
|
//! the `databases` table as detailed in the [Environment Variables
|
||||||
|
//! configuration
|
||||||
|
//! guide](https://rocket.rs/master/guide/configuration/#environment-variables):
|
||||||
|
//!
|
||||||
|
//! ```bash
|
||||||
|
//! ROCKET_DATABASES='{my_db={url="db.sqlite"}}'
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! Multiple databases can be specified in the `ROCKET_DATABASES` environment variable
|
||||||
|
//! as well by comma separating them:
|
||||||
|
//!
|
||||||
|
//! ```bash
|
||||||
|
//! ROCKET_DATABASES='{my_db={url="db.sqlite"},my_pg_db={url="postgres://root:root@localhost/my_pg_db"}}'
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! ## Guard Types
|
||||||
|
//!
|
||||||
|
//! Once a database has been configured, the `#[database]` attribute can be used
|
||||||
|
//! to tie a type in your application to a configured database. The database
|
||||||
|
//! attributes accepts a single string parameter that indicates the name of the
|
||||||
|
//! database. This corresponds to the database name set as the database's
|
||||||
|
//! configuration key.
|
||||||
|
//!
|
||||||
|
//! The macro generates a [`FromRequest`] implementation for the decorated type,
|
||||||
|
//! allowing the type to be used as a request guard. This implementation
|
||||||
|
//! retrieves a connection from the database pool or fails with a
|
||||||
|
//! `Status::ServiceUnavailable` if connecting to the database times out.
|
||||||
|
//!
|
||||||
|
//! The macro will also generate two inherent methods on the decorated type:
|
||||||
|
//!
|
||||||
|
//! * `fn fairing() -> impl Fairing`
|
||||||
|
//!
|
||||||
|
//! Returns a fairing that initializes the associated database connection
|
||||||
|
//! pool.
|
||||||
|
//!
|
||||||
|
//! * `async fn get_one(&Rocket) -> Option<Self>`
|
||||||
|
//!
|
||||||
|
//! Retrieves a connection wrapper from the configured pool. Returns `Some`
|
||||||
|
//! as long as `Self::fairing()` has been attached.
|
||||||
|
//!
|
||||||
|
//! The attribute can only be applied to unit-like structs with one type. The
|
||||||
|
//! internal type of the structure must implement [`Poolable`].
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! # extern crate rocket;
|
||||||
|
//! # #[macro_use] extern crate rocket_contrib;
|
||||||
|
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
||||||
|
//! # mod test {
|
||||||
|
//! use rocket_contrib::databases::diesel;
|
||||||
|
//!
|
||||||
|
//! #[database("my_db")]
|
||||||
|
//! struct MyDatabase(diesel::SqliteConnection);
|
||||||
|
//! # }
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! Other databases can be used by specifying their respective [`Poolable`]
|
||||||
|
//! type:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! # extern crate rocket;
|
||||||
|
//! # #[macro_use] extern crate rocket_contrib;
|
||||||
|
//! # #[cfg(feature = "postgres_pool")]
|
||||||
|
//! # mod test {
|
||||||
|
//! use rocket_contrib::databases::postgres;
|
||||||
|
//!
|
||||||
|
//! #[database("my_pg_db")]
|
||||||
|
//! struct MyPgDatabase(postgres::Client);
|
||||||
|
//! # }
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! The fairing returned from the generated `fairing()` method _must_ be
|
||||||
|
//! attached for the request guard implementation to succeed. Putting the pieces
|
||||||
|
//! together, a use of the `#[database]` attribute looks as follows:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! # #[macro_use] extern crate rocket;
|
||||||
|
//! # #[macro_use] extern crate rocket_contrib;
|
||||||
|
//! #
|
||||||
|
//! # #[cfg(feature = "diesel_sqlite_pool")] {
|
||||||
|
//! # use rocket::figment::{value::{Map, Value}, util::map};
|
||||||
|
//! use rocket_contrib::databases::diesel;
|
||||||
|
//!
|
||||||
|
//! #[database("my_db")]
|
||||||
|
//! struct MyDatabase(diesel::SqliteConnection);
|
||||||
|
//!
|
||||||
|
//! #[launch]
|
||||||
|
//! fn rocket() -> _ {
|
||||||
|
//! # let db: Map<_, Value> = map![
|
||||||
|
//! # "url" => "db.sqlite".into(), "pool_size" => 10.into()
|
||||||
|
//! # ];
|
||||||
|
//! # let figment = rocket::Config::figment().merge(("databases", map!["my_db" => db]));
|
||||||
|
//! rocket::custom(figment).attach(MyDatabase::fairing())
|
||||||
|
//! }
|
||||||
|
//! # }
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! ## Handlers
|
||||||
|
//!
|
||||||
|
//! Finally, use your type as a request guard in a handler to retrieve a
|
||||||
|
//! connection wrapper for the database:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! # #[macro_use] extern crate rocket;
|
||||||
|
//! # #[macro_use] extern crate rocket_contrib;
|
||||||
|
//! #
|
||||||
|
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
||||||
|
//! # mod test {
|
||||||
|
//! # use rocket_contrib::databases::diesel;
|
||||||
|
//! #[database("my_db")]
|
||||||
|
//! struct MyDatabase(diesel::SqliteConnection);
|
||||||
|
//!
|
||||||
|
//! #[get("/")]
|
||||||
|
//! fn my_handler(conn: MyDatabase) {
|
||||||
|
//! // ...
|
||||||
|
//! }
|
||||||
|
//! # }
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! A connection can be retrieved and used with the `run()` method:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! # #[macro_use] extern crate rocket;
|
||||||
|
//! # #[macro_use] extern crate rocket_contrib;
|
||||||
|
//! #
|
||||||
|
//! # #[cfg(feature = "diesel_sqlite_pool")]
|
||||||
|
//! # mod test {
|
||||||
|
//! # use rocket_contrib::databases::diesel;
|
||||||
|
//! # type Data = ();
|
||||||
|
//! #[database("my_db")]
|
||||||
|
//! struct MyDatabase(diesel::SqliteConnection);
|
||||||
|
//!
|
||||||
|
//! fn load_from_db(conn: &diesel::SqliteConnection) -> Data {
|
||||||
|
//! // Do something with connection, return some data.
|
||||||
|
//! # ()
|
||||||
|
//! }
|
||||||
|
//!
|
||||||
|
//! #[get("/")]
|
||||||
|
//! async fn my_handler(mut conn: MyDatabase) -> Data {
|
||||||
|
//! conn.run(|c| load_from_db(c)).await
|
||||||
|
//! }
|
||||||
|
//! # }
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! # Database Support
|
||||||
|
//!
|
||||||
|
//! Built-in support is provided for many popular databases and drivers. Support
|
||||||
|
//! can be easily extended by [`Poolable`] implementations.
|
||||||
|
//!
|
||||||
|
//! ## Provided
|
||||||
|
//!
|
||||||
|
//! The list below includes all presently supported database adapters and their
|
||||||
|
//! corresponding [`Poolable`] type.
|
||||||
|
//!
|
||||||
|
// Note: Keep this table in sync with site/guite/6-state.md
|
||||||
|
//! | Kind | Driver | Version | `Poolable` Type | Feature |
|
||||||
|
//! |----------|-----------------------|-----------|--------------------------------|------------------------|
|
||||||
|
//! | MySQL | [Diesel] | `1` | [`diesel::MysqlConnection`] | `diesel_mysql_pool` |
|
||||||
|
//! | MySQL | [`rust-mysql-simple`] | `18` | [`mysql::Conn`] | `mysql_pool` |
|
||||||
|
//! | Postgres | [Diesel] | `1` | [`diesel::PgConnection`] | `diesel_postgres_pool` |
|
||||||
|
//! | Postgres | [Rust-Postgres] | `0.19` | [`postgres::Client`] | `postgres_pool` |
|
||||||
|
//! | Sqlite | [Diesel] | `1` | [`diesel::SqliteConnection`] | `diesel_sqlite_pool` |
|
||||||
|
//! | Sqlite | [`Rusqlite`] | `0.23` | [`rusqlite::Connection`] | `sqlite_pool` |
|
||||||
|
//! | Memcache | [`memcache`] | `0.15` | [`memcache::Client`] | `memcache_pool` |
|
||||||
|
//!
|
||||||
|
//! [Diesel]: https://diesel.rs
|
||||||
|
//! [`rusqlite::Connection`]: https://docs.rs/rusqlite/0.23.0/rusqlite/struct.Connection.html
|
||||||
|
//! [`diesel::SqliteConnection`]: http://docs.diesel.rs/diesel/prelude/struct.SqliteConnection.html
|
||||||
|
//! [`postgres::Client`]: https://docs.rs/postgres/0.19/postgres/struct.Client.html
|
||||||
|
//! [`diesel::PgConnection`]: http://docs.diesel.rs/diesel/pg/struct.PgConnection.html
|
||||||
|
//! [`mysql::Conn`]: https://docs.rs/mysql/18/mysql/struct.Conn.html
|
||||||
|
//! [`diesel::MysqlConnection`]: http://docs.diesel.rs/diesel/mysql/struct.MysqlConnection.html
|
||||||
|
//! [`Rusqlite`]: https://github.com/jgallagher/rusqlite
|
||||||
|
//! [Rust-Postgres]: https://github.com/sfackler/rust-postgres
|
||||||
|
//! [`rust-mysql-simple`]: https://github.com/blackbeam/rust-mysql-simple
|
||||||
|
//! [`diesel::PgConnection`]: http://docs.diesel.rs/diesel/pg/struct.PgConnection.html
|
||||||
|
//! [`memcache`]: https://github.com/aisk/rust-memcache
|
||||||
|
//! [`memcache::Client`]: https://docs.rs/memcache/0.15/memcache/struct.Client.html
|
||||||
|
//!
|
||||||
|
//! The above table lists all the supported database adapters in this library.
|
||||||
|
//! In order to use particular `Poolable` type that's included in this library,
|
||||||
|
//! you must first enable the feature listed in the "Feature" column. The
|
||||||
|
//! interior type of your decorated database type should match the type in the
|
||||||
|
//! "`Poolable` Type" column.
|
||||||
|
//!
|
||||||
|
//! ## Extending
|
||||||
|
//!
|
||||||
|
//! Extending Rocket's support to your own custom database adapter (or other
|
||||||
|
//! database-like struct that can be pooled by `r2d2`) is as easy as
|
||||||
|
//! implementing the [`Poolable`] trait. See the documentation for [`Poolable`]
|
||||||
|
//! for more details on how to implement it.
|
||||||
|
//!
|
||||||
|
//! [`FromRequest`]: rocket::request::FromRequest
|
||||||
|
//! [request guards]: rocket::request::FromRequest
|
||||||
|
//! [`Poolable`]: crate::databases::Poolable
|
||||||
|
|
||||||
|
pub extern crate r2d2;
|
||||||
|
|
||||||
|
#[cfg(any(
|
||||||
|
feature = "diesel_sqlite_pool",
|
||||||
|
feature = "diesel_postgres_pool",
|
||||||
|
feature = "diesel_mysql_pool"
|
||||||
|
))]
|
||||||
|
pub extern crate diesel;
|
||||||
|
|
||||||
|
#[cfg(feature = "postgres_pool")] pub extern crate postgres;
|
||||||
|
#[cfg(feature = "postgres_pool")] pub extern crate r2d2_postgres;
|
||||||
|
|
||||||
|
#[cfg(feature = "mysql_pool")] pub extern crate mysql;
|
||||||
|
#[cfg(feature = "mysql_pool")] pub extern crate r2d2_mysql;
|
||||||
|
|
||||||
|
#[cfg(feature = "sqlite_pool")] pub extern crate rusqlite;
|
||||||
|
#[cfg(feature = "sqlite_pool")] pub extern crate r2d2_sqlite;
|
||||||
|
|
||||||
|
#[cfg(feature = "memcache_pool")] pub extern crate memcache;
|
||||||
|
#[cfg(feature = "memcache_pool")] pub extern crate r2d2_memcache;
|
||||||
|
|
||||||
|
mod poolable;
|
||||||
|
mod config;
|
||||||
|
mod error;
|
||||||
|
mod connection;
|
||||||
|
|
||||||
|
pub use self::poolable::{Poolable, PoolResult};
|
||||||
|
pub use self::config::Config;
|
||||||
|
pub use self::error::Error;
|
||||||
|
|
||||||
|
#[doc(hidden)]
|
||||||
|
pub use rocket_contrib_codegen::*;
|
||||||
|
|
||||||
|
#[doc(hidden)]
|
||||||
|
pub use self::connection::*;
|
||||||
|
|
@ -0,0 +1,195 @@
|
||||||
|
use r2d2::ManageConnection;
|
||||||
|
|
||||||
|
use crate::databases::{Config, Error};
|
||||||
|
|
||||||
|
/// Trait implemented by `r2d2`-based database adapters.
|
||||||
|
///
|
||||||
|
/// # Provided Implementations
|
||||||
|
///
|
||||||
|
/// Implementations of `Poolable` are provided for the following types:
|
||||||
|
///
|
||||||
|
/// * `diesel::MysqlConnection`
|
||||||
|
/// * `diesel::PgConnection`
|
||||||
|
/// * `diesel::SqliteConnection`
|
||||||
|
/// * `postgres::Connection`
|
||||||
|
/// * `mysql::Conn`
|
||||||
|
/// * `rusqlite::Connection`
|
||||||
|
///
|
||||||
|
/// # Implementation Guide
|
||||||
|
///
|
||||||
|
/// As an r2d2-compatible database (or other resource) adapter provider,
|
||||||
|
/// implementing `Poolable` in your own library will enable Rocket users to
|
||||||
|
/// consume your adapter with its built-in connection pooling support.
|
||||||
|
///
|
||||||
|
/// ## Example
|
||||||
|
///
|
||||||
|
/// Consider a library `foo` with the following types:
|
||||||
|
///
|
||||||
|
/// * `foo::ConnectionManager`, which implements [`r2d2::ManageConnection`]
|
||||||
|
/// * `foo::Connection`, the `Connection` associated type of
|
||||||
|
/// `foo::ConnectionManager`
|
||||||
|
/// * `foo::Error`, errors resulting from manager instantiation
|
||||||
|
///
|
||||||
|
/// In order for Rocket to generate the required code to automatically provision
|
||||||
|
/// a r2d2 connection pool into application state, the `Poolable` trait needs to
|
||||||
|
/// be implemented for the connection type. The following example implements
|
||||||
|
/// `Poolable` for `foo::Connection`:
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// # mod foo {
|
||||||
|
/// # use std::fmt;
|
||||||
|
/// # use rocket_contrib::databases::r2d2;
|
||||||
|
/// # #[derive(Debug)] pub struct Error;
|
||||||
|
/// # impl std::error::Error for Error { }
|
||||||
|
/// # impl fmt::Display for Error {
|
||||||
|
/// # fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { Ok(()) }
|
||||||
|
/// # }
|
||||||
|
/// #
|
||||||
|
/// # pub struct Connection;
|
||||||
|
/// # pub struct ConnectionManager;
|
||||||
|
/// #
|
||||||
|
/// # type Result<T> = std::result::Result<T, Error>;
|
||||||
|
/// #
|
||||||
|
/// # impl ConnectionManager {
|
||||||
|
/// # pub fn new(url: &str) -> Result<Self> { Err(Error) }
|
||||||
|
/// # }
|
||||||
|
/// #
|
||||||
|
/// # impl self::r2d2::ManageConnection for ConnectionManager {
|
||||||
|
/// # type Connection = Connection;
|
||||||
|
/// # type Error = Error;
|
||||||
|
/// # fn connect(&self) -> Result<Connection> { panic!(()) }
|
||||||
|
/// # fn is_valid(&self, _: &mut Connection) -> Result<()> { panic!() }
|
||||||
|
/// # fn has_broken(&self, _: &mut Connection) -> bool { panic!() }
|
||||||
|
/// # }
|
||||||
|
/// # }
|
||||||
|
/// use rocket_contrib::databases::{r2d2, Error, Config, Poolable, PoolResult};
|
||||||
|
///
|
||||||
|
/// impl Poolable for foo::Connection {
|
||||||
|
/// type Manager = foo::ConnectionManager;
|
||||||
|
/// type Error = foo::Error;
|
||||||
|
///
|
||||||
|
/// fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
||||||
|
/// let config = Config::from(db_name, rocket)?;
|
||||||
|
/// let manager = foo::ConnectionManager::new(&config.url).map_err(Error::Custom)?;
|
||||||
|
/// Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
||||||
|
/// }
|
||||||
|
/// }
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// In this example, `ConnectionManager::new()` method returns a `foo::Error` on
|
||||||
|
/// failure. The [`Error`] enum consolidates this type, the `r2d2::Error` type
|
||||||
|
/// that can result from `r2d2::Pool::builder()`, and the
|
||||||
|
/// [`figment::Error`](rocket::figment::Error) type from
|
||||||
|
/// `database::Config::from()`.
|
||||||
|
///
|
||||||
|
/// In the event that a connection manager isn't fallible (as is the case with
|
||||||
|
/// Diesel's r2d2 connection manager, for instance), the associated error type
|
||||||
|
/// for the `Poolable` implementation should be `std::convert::Infallible`.
|
||||||
|
///
|
||||||
|
/// For more concrete example, consult Rocket's existing implementations of
|
||||||
|
/// [`Poolable`].
|
||||||
|
pub trait Poolable: Send + Sized + 'static {
|
||||||
|
/// The associated connection manager for the given connection type.
|
||||||
|
type Manager: ManageConnection<Connection=Self>;
|
||||||
|
|
||||||
|
/// The associated error type in the event that constructing the connection
|
||||||
|
/// manager and/or the connection pool fails.
|
||||||
|
type Error: std::fmt::Debug;
|
||||||
|
|
||||||
|
/// Creates an `r2d2` connection pool for `Manager::Connection`, returning
|
||||||
|
/// the pool on success.
|
||||||
|
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self>;
|
||||||
|
}
|
||||||
|
|
||||||
|
/// A type alias for the return type of [`Poolable::pool()`].
|
||||||
|
#[allow(type_alias_bounds)]
|
||||||
|
pub type PoolResult<P: Poolable> = Result<r2d2::Pool<P::Manager>, Error<P::Error>>;
|
||||||
|
|
||||||
|
#[cfg(feature = "diesel_sqlite_pool")]
|
||||||
|
impl Poolable for diesel::SqliteConnection {
|
||||||
|
type Manager = diesel::r2d2::ConnectionManager<diesel::SqliteConnection>;
|
||||||
|
type Error = std::convert::Infallible;
|
||||||
|
|
||||||
|
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
||||||
|
let config = Config::from(db_name, rocket)?;
|
||||||
|
let manager = diesel::r2d2::ConnectionManager::new(&config.url);
|
||||||
|
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(feature = "diesel_postgres_pool")]
|
||||||
|
impl Poolable for diesel::PgConnection {
|
||||||
|
type Manager = diesel::r2d2::ConnectionManager<diesel::PgConnection>;
|
||||||
|
type Error = std::convert::Infallible;
|
||||||
|
|
||||||
|
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
||||||
|
let config = Config::from(db_name, rocket)?;
|
||||||
|
let manager = diesel::r2d2::ConnectionManager::new(&config.url);
|
||||||
|
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(feature = "diesel_mysql_pool")]
|
||||||
|
impl Poolable for diesel::MysqlConnection {
|
||||||
|
type Manager = diesel::r2d2::ConnectionManager<diesel::MysqlConnection>;
|
||||||
|
type Error = std::convert::Infallible;
|
||||||
|
|
||||||
|
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
||||||
|
let config = Config::from(db_name, rocket)?;
|
||||||
|
let manager = diesel::r2d2::ConnectionManager::new(&config.url);
|
||||||
|
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// TODO: Add a feature to enable TLS in `postgres`; parse a suitable `config`.
|
||||||
|
#[cfg(feature = "postgres_pool")]
|
||||||
|
impl Poolable for postgres::Client {
|
||||||
|
type Manager = r2d2_postgres::PostgresConnectionManager<postgres::tls::NoTls>;
|
||||||
|
type Error = postgres::Error;
|
||||||
|
|
||||||
|
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
||||||
|
let config = Config::from(db_name, rocket)?;
|
||||||
|
let url = config.url.parse().map_err(Error::Custom)?;
|
||||||
|
let manager = r2d2_postgres::PostgresConnectionManager::new(url, postgres::tls::NoTls);
|
||||||
|
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(feature = "mysql_pool")]
|
||||||
|
impl Poolable for mysql::Conn {
|
||||||
|
type Manager = r2d2_mysql::MysqlConnectionManager;
|
||||||
|
type Error = std::convert::Infallible;
|
||||||
|
|
||||||
|
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
||||||
|
let config = Config::from(db_name, rocket)?;
|
||||||
|
let opts = mysql::OptsBuilder::from_opts(&config.url);
|
||||||
|
let manager = r2d2_mysql::MysqlConnectionManager::new(opts);
|
||||||
|
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(feature = "sqlite_pool")]
|
||||||
|
impl Poolable for rusqlite::Connection {
|
||||||
|
type Manager = r2d2_sqlite::SqliteConnectionManager;
|
||||||
|
type Error = std::convert::Infallible;
|
||||||
|
|
||||||
|
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
||||||
|
let config = Config::from(db_name, rocket)?;
|
||||||
|
let manager = r2d2_sqlite::SqliteConnectionManager::file(&*config.url);
|
||||||
|
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(feature = "memcache_pool")]
|
||||||
|
impl Poolable for memcache::Client {
|
||||||
|
type Manager = r2d2_memcache::MemcacheConnectionManager;
|
||||||
|
// Unused, but we might want it in the future without a breaking change.
|
||||||
|
type Error = memcache::MemcacheError;
|
||||||
|
|
||||||
|
fn pool(db_name: &str, rocket: &rocket::Rocket) -> PoolResult<Self> {
|
||||||
|
let config = Config::from(db_name, rocket)?;
|
||||||
|
let manager = r2d2_memcache::MemcacheConnectionManager::new(&*config.url);
|
||||||
|
Ok(r2d2::Pool::builder().max_size(config.pool_size).build(manager)?)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
Loading…
Reference in New Issue