Expand description
Asynchronous database driver connection pooling integration for Rocket.
§Quickstart
-
Add
rocket_db_poolsas a dependency with one or more database driver features enabled:[dependencies.rocket_db_pools] version = "=0.4.0-rc.1" features = ["sqlx_sqlite"] -
Choose a name for your database, here
sqlite_logs. Configure at least a URL for the database:[default.databases.sqlite_logs] url = "/path/to/database.sqlite" -
Derive
Databasefor a unit type (Logshere) which wraps the selected driver’sPooltype (see the driver table) and is decorated with#[database("name")]. AttachType::init()to your application’sRocketto initialize the database pool:use rocket_db_pools::{sqlx, Database}; #[derive(Database)] #[database("sqlite_logs")] struct Logs(sqlx::SqlitePool); #[launch] fn rocket() -> _ { rocket::build().attach(Logs::init()) } -
Use
Connection<Type>as a request guard to retrieve an active database connection, which dereferences to the native type in theConnectionderef column.use rocket_db_pools::Connection; use rocket_db_pools::sqlx::Row; #[get("/<id>")] async fn read(mut db: Connection<Logs>, id: i64) -> Option<Log> { sqlx::query("SELECT content FROM logs WHERE id = ?").bind(id) .fetch_one(&mut **db).await .and_then(|r| Ok(Log(r.try_get(0)?))) .ok() }Alternatively, use a reference to the database type as a request guard to retrieve the entire pool, but note that unlike retrieving a
Connection, doing so does not guarantee that a connection is available:use rocket_db_pools::sqlx::Row; #[get("/<id>")] async fn read(db: &Logs, id: i64) -> Option<Log> { sqlx::query("SELECT content FROM logs WHERE id = ?").bind(id) .fetch_one(&db.0).await .and_then(|r| Ok(Log(r.try_get(0)?))) .ok() }
§Supported Drivers
At present, this crate supports four drivers: deadpool, sqlx,
mongodb, and diesel. Each driver may support multiple databases.
Drivers have a varying degree of support for graceful shutdown, affected by
the Type::init() fairing on Rocket shutdown.
§deadpool (v0.13)
| Database | Feature | Pool Type | Connection Deref |
|---|---|---|---|
| Postgres | deadpool_postgres (v0.14) | deadpool_postgres::Pool | deadpool_postgres::ClientWrapper |
| Redis | deadpool_redis (v0.23) | deadpool_redis::Pool | deadpool_redis::Connection |
On shutdown, new connections are denied. Shutdown does not wait for connections to be returned.
See Postgres TLS to connect to Postgres over TLS.
§sqlx (v0.9)
| Database | Feature | Pool Type | Connection Deref |
|---|---|---|---|
| Postgres | sqlx_postgres | sqlx::PgPool | sqlx::pool::PoolConnection<Postgres> |
| MySQL | sqlx_mysql | sqlx::MySqlPool | sqlx::pool::PoolConnection<MySql> |
| SQLite | sqlx_sqlite | sqlx::SqlitePool | sqlx::pool::PoolConnection<Sqlite> |
On shutdown, new connections are denied. Shutdown waits for connections to be returned.
§mongodb (v3)
| Database | Feature | Pool Type and Connection Deref |
|---|---|---|
| MongoDB | mongodb | mongodb::Client |
Graceful shutdown is not supported.
§diesel (v2)
| Database | Feature | Pool Type | Connection Deref |
|---|---|---|---|
| Postgres | diesel_postgres | diesel::PgPool | diesel::AsyncPgConnection |
| MySQL | diesel_mysql | diesel::MysqlPool | diesel::AsyncMysqlConnection |
| SQLite | diesel_sqlite | diesel::SqlitePool | diesel::SyncConnectionWrapper<diesel::SqliteConnection> |
See diesel for usage details.
On shutdown, new connections are denied. Shutdown does not wait for connections to be returned.
See Postgres TLS to connect to Postgres over TLS.
§Postgres TLS
By default, the deadpool_postgres and diesel_postgres drivers connect
without TLS: a URL with sslmode=require fails to connect. To enable TLS
for these drivers, also enable the postgres_rustls_native_certs feature:
[dependencies.rocket_db_pools]
version = "=0.4.0-rc.1"
features = ["diesel_postgres", "postgres_rustls_native_certs"]To require TLS, set sslmode=require in the database URL. With
sslmode=prefer, a connection without TLS is allowed if the server does not
support TLS. The server’s certificate and hostname are verified using the
platform’s native root certificates.
To trust a private CA, set SSL_CERT_FILE to a PEM certificate bundle or
SSL_CERT_DIR to a directory of PEM certificates. These replace the native
roots. Errors loading certificates are logged. If no root certificates can
be loaded, TLS connections fail.
The sqlx_postgres driver supports TLS without additional features.
§Enabling Additional Driver Features
Only the minimal features for each driver crate are enabled by
rocket_db_pools. To use additional driver functionality exposed via its
crate’s features, you’ll need to depend on the crate directly with those
features enabled in Cargo.toml:
[dependencies.sqlx]
version = "0.9"
default-features = false
features = ["macros", "migrate"]
[dependencies.rocket_db_pools]
version = "=0.4.0-rc.1"
features = ["sqlx_sqlite"]§Configuration
Configuration for a database named db_name is deserialized from a
databases.db_name configuration parameter into a Config structure via
Rocket’s configuration facilities. By default,
configuration can be provided in Rocket.toml:
[default.databases.db_name]
url = "db.sqlite"
# Only `url` is required. These have sane defaults and are optional.
min_connections = 64
max_connections = 1024
connect_timeout = 5
idle_timeout = 120Or via environment variables:
ROCKET_DATABASES='{db_name={url="db.sqlite",idle_timeout=120}}'See Config for details on configuration parameters.
Note: deadpool and diesel drivers do not support and thus ignore the
min_connections value. For these drivers, idle_timeout limits the time
allowed to recycle a connection before reuse, including any health check.
It does not close idle connections. By default, no timeout is set.
§Redis
The deadpool_redis driver accepts an additional response_timeout option:
[default.databases.redis]
url = "redis://localhost:6379"
response_timeout = 0.5This option limits how long the client waits for a command’s response, in
seconds, and defaults to 0.5. Both integer and fractional values are
accepted. Set response_timeout = 0 to disable the timeout, for example,
when using blocking commands such as BLPOP. A timeout does not cancel a
command already executing on Redis. Negative, nonfinite, out-of-range, and
nonnumeric values result in an Error::Config during initialization.
Other drivers ignore this option.
The Redis driver’s connection timeout is disabled. Instead, Deadpool limits
both the time spent waiting for a pooled connection and the time spent
creating a connection to Config::connect_timeout seconds each. These
limits apply separately. Redis health checks also use response_timeout,
even when idle_timeout is unset.
§Driver Defaults
Some drivers provide configuration defaults different from the underlying database’s defaults. A best-effort attempt is made to document those differences below:
-
deadpool_redis- response timeout :
0.5seconds - connection timeout : disabled (Deadpool’s creation timeout applies)
- response timeout :
-
sqlx_sqlite- foreign keys :
enabled - journal mode :
WAL - create-missing :
enabled - synchronous :
full(even whenWAL) - busy timeout :
connect_timeout
- foreign keys :
-
sqlx_postgres- sslmode :
prefer - statement-cache-capacity :
100 - user : result of
whoami
- sslmode :
-
sqlx_mysql- sslmode :
PREFERRED - statement-cache-capacity :
100
- sslmode :
§Customization
To customize a database driver before its pool is created, use
Database::custom(). The pool must implement Configurable, as SQLx
pools and MongoDB clients do. This method takes a function that receives a
reference to the database’s Config and the driver’s configuration
options, with Rocket’s configuration and defaults already applied. The
returned options are used to create the pool.
For SQLx, the options are a tuple of pool and connection options. The pool
options allow further customization via methods such as after_connect().
For MongoDB, the options are a ClientOptions structure. See
Configurable::Options for the configuration types used by each driver.
As an example, the following sets MongoDB’s application name:
use rocket_db_pools::{mongodb, Database};
#[derive(Database)]
#[database("mongo_db")]
struct Db(mongodb::Client);
fn main() {
rocket::build().attach(Db::custom(|_config, mut options| {
options.app_name = Some("my-app".into());
options
}));
}If configuration can fail, use Database::try_custom() instead. Returning
an error from the callback aborts launch.
§SQLite Extensions
SQLite extensions can be loaded via SQLx’s
SqliteConnectOptions::extension() method in a Database::custom()
callback. The method is unsafe: the extension library must be trusted
whenever a connection is created, including connections created after
initialization. For example, to load the rot13 extension:
use rocket_db_pools::{sqlx, Database};
#[derive(Database)]
#[database("sqlite_db")]
struct Db(sqlx::SqlitePool);
fn main() {
rocket::build().attach(Db::custom(|_config, (pool, connection)| {
// SAFETY: this library is trusted for the pool's lifetime.
let connection = unsafe { connection.extension("rot13") };
(pool, connection)
}));
}To use extension names from application configuration, capture the configuration in the callback.
§Extending
Any database driver can implement support for this library by implementing
the Pool trait. To support customization via Database::custom(),
also implement Configurable.
Re-exports§
pub use rocket;pub use deadpool_postgres;pub use deadpool_redis;pub use mongodb;pub use sqlx;
Modules§
- diesel
- Re-export of
dieselwith prelude types overridden withasyncvariants fromdiesel_async. - figment
- Re-export of the
figmentcrate. Semi-hierarchical configuration so con-free, it’s unreal.
Structs§
- Config
- Base configuration for all database drivers.
- Connection
- A request guard which retrieves a single connection to a
Database. - Initializer
- A
Fairingwhich initializes aDatabaseand its connection pool.
Enums§
- Error
- A general error type for use by
Poolimplementors and returned by theConnectionrequest guard.
Traits§
- Configurable
- A
Poolthat supports customization during initialization. - Database
- Derivable trait which ties a database
Poolwith a configuration name. - Pool
- Generic
Databasedriver connection pool trait.