Traits, utilities, and a macro for easy database connection pooling.
Overview
This crate provides traits, utilities, and a procedural macro for
configuring and accessing database connection pools in Rocket. A database
connection pool is a data structure that maintains active database
connections for later use in the application. This implementation is backed
by [r2d2
] and exposes connections through request guards.
Databases are individually configured through Rocket's regular configuration mechanisms. Connecting a Rocket application to a database using this library occurs in three simple steps:
- Configure your databases in
Rocket.toml
. (see Configuration) - Associate a request guard type and fairing with each database. (see Guard Types)
- 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_sync_db_pools
must be enabled:
[]
= "0.1.0-rc.1"
= ["diesel_sqlite_pool"]
See 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:
[]
= { = "/path/to/database.sqlite" }
In your application's source code, one-time:
# extern crate rocket;
#
#
Whenever a connection to the database is needed:
# extern crate rocket;
# extern crate rocket_sync_db_pools;
#
#
#
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:
# Option 1:
[]
= { = "db.sqlite" }
# Option 2:
[]
= "postgres://root:root@localhost/my_db"
# With a `pool_size` key:
[]
= { = "db.sqlite", = 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 * 4)
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:
#
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
attribute 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 also generates 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<P: Phase>(&Rocket<P>) -> 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
.
# extern crate rocket_sync_db_pools;
#
#
Other databases can be used by specifying their respective Poolable
type:
# extern crate rocket_sync_db_pools;
#
#
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:
# extern crate rocket;
# extern crate rocket_sync_db_pools;
#
#
Handlers
Finally, use your type as a request guard in a handler to retrieve a connection wrapper for the database:
# extern crate rocket;
# extern crate rocket_sync_db_pools;
#
#
#
A connection can be retrieved and used with the run()
method:
# extern crate rocket;
# extern crate rocket_sync_db_pools;
#
#
#
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.
Kind | Driver | Version | Poolable Type |
Feature |
---|---|---|---|---|
MySQL | Diesel | 1 |
diesel::MysqlConnection |
diesel_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.24 |
rusqlite::Connection |
sqlite_pool |
Memcache | memcache |
0.15 |
memcache::Client |
memcache_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.