Skip to main content

Crate rocket_db_pools

Crate rocket_db_pools 

Source
Expand description

Asynchronous database driver connection pooling integration for Rocket.

§Quickstart

  1. Add rocket_db_pools as a dependency with one or more database driver features enabled:

    [dependencies.rocket_db_pools]
    version = "=0.4.0-rc.1"
    features = ["sqlx_sqlite"]
  2. 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"
  3. Derive Database for a unit type (Logs here) which wraps the selected driver’s Pool type (see the driver table) and is decorated with #[database("name")]. Attach Type::init() to your application’s Rocket to 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())
    }
  4. Use Connection<Type> as a request guard to retrieve an active database connection, which dereferences to the native type in the Connection deref 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)

DatabaseFeaturePool TypeConnection Deref
Postgresdeadpool_postgres (v0.14)deadpool_postgres::Pooldeadpool_postgres::ClientWrapper
Redisdeadpool_redis (v0.23)deadpool_redis::Pooldeadpool_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)

On shutdown, new connections are denied. Shutdown waits for connections to be returned.

§mongodb (v3)

DatabaseFeaturePool Type and Connection Deref
MongoDBmongodbmongodb::Client

Graceful shutdown is not supported.

§diesel (v2)

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 = 120

Or 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.5

This 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.5 seconds
    • connection timeout : disabled (Deadpool’s creation timeout applies)
  • sqlx_sqlite

    • foreign keys : enabled
    • journal mode : WAL
    • create-missing : enabled
    • synchronous : full (even when WAL)
    • busy timeout : connect_timeout
  • sqlx_postgres

    • sslmode : prefer
    • statement-cache-capacity : 100
    • user : result of whoami
  • sqlx_mysql

    • sslmode : PREFERRED
    • statement-cache-capacity : 100

§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 diesel with prelude types overridden with async variants from diesel_async.
figment
Re-export of the figment crate. 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 Fairing which initializes a Database and its connection pool.

Enums§

Error
A general error type for use by Pool implementors and returned by the Connection request guard.

Traits§

Configurable
A Pool that supports customization during initialization.
Database
Derivable trait which ties a database Pool with a configuration name.
Pool
Generic Database driver connection pool trait.

Derive Macros§

Database
Automatic derive for the Database trait.