bb8 Documentation

bb8 is an asynchronous connection pool designed for use with tokio. It prevents the inefficiency and resource exhaustion caused by opening new database connections for every request by maintaining a set of open connections that are reused.

bb8 is backend-agnostic. It relies on the ManageConnection trait, which implementors use to provide database-specific logic for creating new connections and verifying their health. To use bb8 with a specific database, you typically use an adapter crate (e.g., bb8-postgres or bb8-redis).

The QueueStrategy determines how the pool selects an idle connection when a user requests one:

• Fifo (First In, First Out): Behaves like a queue. It spreads load evenly across all existing connections, which helps prevent connections from idling out, but keeps more connections active.
• Lifo (Last In, First Out): Behaves like a stack. It reuses the most recently used connection. This helps keep the total pool size small by allowing older, unused connections to reach their idle timeout and be evicted.

To create a new Pool, use Pool::builder() to configure settings and then call .build(manager) or .build_unchecked(manager).

• build(manager): An async method that waits until the configured minimum number of connections is established before returning the pool.
• build_unchecked(manager): Returns the pool immediately and spawns a background task to establish connections.

let manager = MyManager::new();
let pool = Pool::builder()
    .max_size(20)
    .min_idle(Some(5))
    .build(manager)
    .await?;

To use bb8, you first create a connection manager (provided by your database adapter), then use bb8::Pool::builder() to configure and build the pool. You can set constraints like max_size.

To acquire a connection, call pool.get().await. The connection is automatically returned to the pool when the returned guard falls out of scope.

#[tokio::main]
async fn main() {
    let manager = bb8_foodb::FooConnectionManager::new("localhost:1234");
    let pool = bb8::Pool::builder()
        .max_size(15)
        .build(manager)
        .await
        .unwrap();

    for _ in 0..20 {
        let pool = pool.clone();
        tokio::spawn(async move {
            let conn = pool.get().await.unwrap();
            // use the connection
            // it will be returned to the pool when it falls out of scope.
        });
    }
}

Once you have a Pool instance, you can request a connection by calling .get().await. This returns a PooledConnection, which is a wrapper around the underlying connection. When the PooledConnection is dropped (falls out of scope), the connection is automatically returned to the pool for reuse.

let conn = pool.get().await.unwrap();
// use the connection
// it will be returned to the pool when it falls out of scope.

Use Pool::get() to retrieve a connection managed by the pool. This returns a PooledConnection which implements Deref and DerefMut to allow direct access to the underlying connection. When the PooledConnection is dropped, the connection is automatically returned to the pool.

If you need to move the connection to a different thread or leak the pool's lifetime, use Pool::get_owned(). This returns a PooledConnection<'static, M> by cloning the pool's inner state.

// Standard usage (preferred)
let conn = pool.get().await?;
// Use conn like the underlying connection type
conn.execute("SELECT 1").await?;

// Owned usage (for moving across lifetimes)
let owned_conn = pool.get_owned().await?;

To create a new connection pool, use the Pool::builder() pattern. You must pass an object that implements the ManageConnection trait to the .build(manager) method. This method is asynchronous and returns a Result<Pool<M>, RunError>.

let manager = bb8_foodb::FooConnectionManager::new("localhost:1234");
let pool = bb8::Pool::builder().build(manager).await.unwrap();

Creates a new RedisConnectionManager. The input info must implement redis::IntoConnectionInfo (such as a connection string).

Returns Ok(RedisConnectionManager) or a RedisError if the connection info is invalid.

impl RedisConnectionManager {
    pub fn new<T: IntoConnectionInfo>(info: T) -> Result<Self, RedisError>
}