Trait rocket_sync_db_pools::Poolable

source ·

pub trait Poolable: Send + Sized + 'static {
    type Manager: ManageConnection<Connection = Self>;
    type Error: Debug;

    // Required method
    fn pool(db_name: &str, rocket: &Rocket<Build>) -> PoolResult<Self>;
}

Expand description

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
rusqlite::Connection

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:

use std::time::Duration;
use rocket::{Rocket, Build};
use rocket_sync_db_pools::{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<Build>) -> 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)
            .connection_timeout(Duration::from_secs(config.timeout as u64))
            .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 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.