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:
-
The
Errorassociated type is set toError. -
The pool is initialized and returned in
init(), wrapping initialization errors inError::Init. -
A connection is retrieved in
get(), wrapping errors inError::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§
sourcetype Connection
type Connection
The connection type managed by this pool, returned by Self::get().
sourcetype Error: Error
type Error: Error
The error type returned by Self::init() and Self::get().
Required Methods§
sourcefn 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 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.
sourcefn 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 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.
sourcefn close<'life0, 'async_trait>(
&'life0 self,
) -> Pin<Box<dyn Future<Output = ()> + 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,
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.