logo
pub trait Pool: Sized + Send + Sync + 'static {
    type Connection;
    type Error: Error;

    fn init<'life0, 'async_trait>(
        figment: &'life0 Figment
    ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Error>> + Send + 'async_trait>>
    where
        'life0: 'async_trait,
        Self: 'async_trait
; fn get<'life0, 'async_trait>(
        &'life0 self
    ) -> Pin<Box<dyn Future<Output = Result<Self::Connection, Self::Error>> + Send + 'async_trait>>
    where
        'life0: 'async_trait,
        Self: 'async_trait
; }
Expand description

Generic Database driver connection pool trait.

This trait provides a generic interface to various database pooling implementations in the Rust ecosystem. It can be implemented by anyone, but this crate provides implementations for common drivers.

Implementations of this trait outside of this crate should be rare. You do not need to implement this trait or understand its specifics to use this crate.

Async Trait

Pool is an async trait. Implementations of Pool must be decorated with an attribute of #[async_trait]:

use rocket::figment::Figment;
use rocket_db_pools::Pool;

#[rocket::async_trait]
impl Pool for MyPool {
    type Connection = Connection;

    type Error = Error;

    async fn init(figment: &Figment) -> Result<Self, Self::Error> {
        todo!("initialize and return an instance of the pool");
    }

    async fn get(&self) -> Result<Self::Connection, Self::Error> {
        todo!("fetch one connection from the pool");
    }
}

Implementing

Implementations of Pool typically trace the following outline:

  1. The Error associated type is set to Error.

  2. A Config is extracted from the figment passed to init.

  3. The pool is initialized and returned in init(), wrapping initialization errors in Error::Init.

  4. A connection is retrieved in get(), wrapping errors in Error::Get.

Concretely, this looks like:

use rocket::figment::Figment;
use rocket_db_pools::{Pool, Config, Error};

#[rocket::async_trait]
impl Pool for MyPool {
    type Connection = Connection;

    type Error = Error<InitError, GetError>;

    async fn init(figment: &Figment) -> Result<Self, Self::Error> {
        // Extract the config from `figment`.
        let config: Config = figment.extract()?;

        // Read config values, initialize `MyPool`. Map errors of type
        // `InitError` to `Error<InitError, _>` with `Error::Init`.
        let pool = MyPool::new(config).map_err(Error::Init)?;

        // Return the fully intialized pool.
        Ok(pool)
    }

    async fn get(&self) -> Result<Self::Connection, Self::Error> {
        // Get one connection from the pool, here via an `acquire()` method.
        // Map errors of type `GetError` to `Error<_, GetError>`.
        self.acquire().map_err(Error::Get)
    }
}

Required Associated Types

The connection type managed by this pool, returned by Self::get().

The error type returned by Self::init() and Self::get().

Required Methods

Constructs a pool from a Value.

It is up to each implementor of Pool to define its accepted configuration value(s) via the Config associated type. Most integrations provided in rocket_db_pools use Config, which accepts a (required) url and an (optional) pool_size.

Errors

This method returns an error if the configuration is not compatible, or if creating a pool failed due to an unavailable database server, insufficient resources, or another database-specific error.

Asynchronously retrieves a connection from the factory or pool.

Errors

This method returns an error if a connection could not be retrieved, such as a preconfigured timeout elapsing or when the database server is unavailable.

Implementations on Foreign Types

Implementors