Trait rocket_db_pools::Pool

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

    // Required methods
    fn init<'life0, 'async_trait>(
        figment: &'life0 Figment,
    ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Self::Connection, Self::Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn close<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: '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");
    }

    async fn close(&self) {
        todo!("gracefully shutdown connection 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 initialized 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)
    }

    async fn close(&self) {
        self.shutdown().await;
    }
}

Required Associated Types§

source

type Connection

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

source

type Error: Error

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

Required Methods§

source

fn init<'life0, 'async_trait>( figment: &'life0 Figment, ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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.

source

fn get<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Self::Connection, Self::Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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.

source

fn close<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Shutdown the connection pool, disallowing any new connections from being retrieved and waking up any tasks with active connections.

The returned future may either resolve when all connections are known to have closed or at any point prior. Details are implementation specific.

Object Safety§

This trait is not object safe.

Implementations on Foreign Types§

source§

impl Pool for Client

source§

type Error = Error<Error, Infallible>

source§

type Connection = Client

source§

fn init<'life0, 'async_trait>( figment: &'life0 Figment, ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

source§

fn get<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Self::Connection, Self::Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

source§

fn close<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

source§

impl<D: Database> Pool for Pool<D>

source§

type Error = Error<Error>

source§

type Connection = PoolConnection<D>

source§

fn init<'life0, 'async_trait>( figment: &'life0 Figment, ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

source§

fn get<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Self::Connection, Self::Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

source§

fn close<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

source§

impl<M: DeadManager, C> Pool for Pool<M, C>
where M::Type: Send, C: Send + Sync + 'static + From<Object<M>>, M::Error: Error,

source§

type Error = Error<PoolError<<M as Manager>::Error>>

source§

type Connection = C

source§

fn init<'life0, 'async_trait>( figment: &'life0 Figment, ) -> Pin<Box<dyn Future<Output = Result<Self, Self::Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

source§

fn get<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Self::Connection, Self::Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

source§

fn close<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Implementors§