[][src]Module rocket_contrib::databases

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)
  2. Associate a request guard type and fairing with each database. (see Guard Types)
  3. Use the request guard to retrieve a connection in a handler. (see Handlers)

For a list of supported databases, see Provided Databases. This support can be easily extended by implementing the Poolable trait. See Extending for more.

Example

Before using this library, the feature corresponding to your database type in rocket_contrib must be enabled:

[dependencies.rocket_contrib]
version = "0.4.2"
default-features = false
features = ["diesel_sqlite_pool"]

See Provided for a list of supported database and their associated feature name.

In Rocket.toml or the equivalent via environment variables:

[global.databases]
sqlite_logs = { url = "/path/to/database.sqlite" }

In your application's source code, one-time:

#![feature(proc_macro_hygiene, decl_macro)]

#[macro_use] extern crate rocket;
#[macro_use] extern crate rocket_contrib;

use rocket_contrib::databases::diesel;

#[database("sqlite_logs")]
struct LogsDbConn(diesel::SqliteConnection);

fn main() {
    rocket::ignite()
       .attach(LogsDbConn::fairing())
       .launch();
}

Whenever a connection to the database is needed:

#[get("/logs/<id>")]
fn get_logs(conn: LogsDbConn, id: usize) -> Result<Logs> {
    Logs::by_id(&*conn, id)
}

Usage

Configuration

Databases can be configured via various mechanisms: Rocket.toml, procedurally via rocket::custom(), or via environment variables.

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:

# 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:

Additionally, all configurations accept the following optional keys:

Additional options may be required or supported by other adapters.

Procedurally

Databases can also be configured procedurally database via rocket::custom(). The example below does just this:

extern crate rocket;

use std::collections::HashMap;
use rocket::config::{Config, Environment, Value};

fn main() {
    let mut database_config = HashMap::new();
    let mut databases = HashMap::new();

    // This is the same as the following TOML:
    // my_db = { url = "database.sqlite" }
    database_config.insert("url", Value::from("database.sqlite"));
    databases.insert("my_db", Value::from(database_config));

    let config = Config::build(Environment::Development)
        .extra("databases", databases)
        .finalize()
        .unwrap();

    rocket::custom(config).launch();
}

Environment Variables

Lastly, databases can be configured via environment variables by specifying the databases table as detailed in the Environment Variables configuration guide:

ROCKET_DATABASES='{my_db={url="db.sqlite"}}'

Multiple databases can be specified in the ROCKET_DATABASES environment variable as well by comma separating them:

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 attribute can only be applied to unit-like structs with one type. The internal type of the structure must implement Poolable.

use rocket_contrib::databases::diesel;

#[database("my_db")]
struct MyDatabase(diesel::SqliteConnection);

Other databases can be used by specifying their respective Poolable type:

use rocket_contrib::databases::postgres;

#[database("my_pg_db")]
struct MyPgDatabase(postgres::Connection);

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 no connections are available. The macro also generates an implementation of the Deref trait with the internal Poolable type as the target.

The macro will also generate two inherent methods on the decorated type:

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:

use rocket_contrib::databases::diesel;

#[database("my_db")]
struct MyDatabase(diesel::SqliteConnection);

fn main() {
    rocket::custom(config)
        .attach(MyDatabase::fairing())
        .launch();
}

Handlers

Finally, simply use your type as a request guard in a handler to retrieve a connection to a given database:

#[database("my_db")]
struct MyDatabase(diesel::SqliteConnection);

#[get("/")]
fn my_handler(conn: MyDatabase) {
    // ...
}

The generated Deref implementation allows easy access to the inner connection type:

#[database("my_db")]
struct MyDatabase(diesel::SqliteConnection);

fn load_from_db(conn: &diesel::SqliteConnection) -> Data {
    // Do something with connection, return some data.
}

#[get("/")]
fn my_handler(conn: MyDatabase) -> Data {
    load_from_db(&*conn)
}

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.

KindDriverVersionPoolable TypeFeature
MySQLDiesel1diesel::MysqlConnectiondiesel_mysql_pool
MySQLrust-mysql-simple16mysql::connmysql_pool
PostgresDiesel1diesel::PgConnectiondiesel_postgres_pool
PostgresRust-Postgres0.15postgres::Connectionpostgres_pool
SqliteDiesel1diesel::SqliteConnectiondiesel_sqlite_pool
SqliteRustqlite0.16rusqlite::Connectionsqlite_pool
Neo4jrusted_cypher1rusted_cypher::GraphClientcypher_pool
Redisredis-rs0.10redis::Connectionredis_pool
MongoDBmongodb0.3.12mongodb::db::Databasemongodb_pool
Memcachememcache0.11memcache::Clientmemcache_pool

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.

Re-exports

pub extern crate r2d2;
pub extern crate diesel;
pub extern crate postgres;
pub extern crate r2d2_postgres;
pub extern crate mysql;
pub extern crate r2d2_mysql;
pub extern crate rusqlite;
pub extern crate r2d2_sqlite;
pub extern crate rusted_cypher;
pub extern crate r2d2_cypher;
pub extern crate redis;
pub extern crate r2d2_redis;
pub extern crate mongodb;
pub extern crate r2d2_mongodb;
pub extern crate memcache;
pub extern crate r2d2_memcache;

Structs

DatabaseConfig

A structure representing a particular database configuration.

Enums

ConfigError

Error returned on invalid database configurations.

DbError

A wrapper around r2d2::Errors or a custom database error type.

Traits

Poolable

Trait implemented by r2d2-based database adapters.

Functions

database_config

Retrieves the database configuration for the database named name.