Module pool 

Connection pools for Hyper database.

This module provides two pools that share a common configuration surface:

• Pool — an async pool built on deadpool, for async/await applications. Created via create_pool.
• ConnectionPool — a synchronous, r2d2-style pool with no Tokio dependency on its hot path, for blocking applications. Created via SyncPoolConfig::build.

Both pools open connections lazily, serialize the first-connection database-creation handshake, recycle connections via a configurable RecycleStrategy / SyncRecycleStrategy, and enforce optional lifetime / idle caps.

Async example

use hyperdb_api::pool::{create_pool, PoolConfig};
use hyperdb_api::CreateMode;

#[tokio::main]
async fn main() -> hyperdb_api::Result<()> {
    // Create a pool configuration
    let config = PoolConfig::new("localhost:7483", "example.hyper")
        .create_mode(CreateMode::CreateIfNotExists)
        .max_size(16);

    // Build the pool
    let pool = create_pool(config)?;

    // Get a connection from the pool
    let conn = pool.get().await.map_err(|e| hyperdb_api::Error::internal(e.to_string()))?;

    // Use the connection
    conn.execute_command("SELECT 1").await?;

    // Connection is returned to pool when dropped
    Ok(())
}

Sync example

use hyperdb_api::pool::SyncPoolConfig;
use hyperdb_api::CreateMode;
use std::time::Duration;

let pool = SyncPoolConfig::new("localhost:7483", "example.hyper")
    .create_mode(CreateMode::CreateIfNotExists)
    .max_size(8)
    .wait_timeout(Some(Duration::from_secs(5)))
    .build();

let conn = pool.get()?;
conn.execute_command("SELECT 1")?;
// Connection returns to the pool when `conn` drops.

Tuning knobs (shared by both pools)

• Recycle strategy (PoolConfig::recycle / SyncPoolConfig::recycle) controls the per-checkout health probe. Defaults to SelectOne (a SELECT 1 round-trip). Use Ping for the connection’s native ping, None to skip the probe on hot paths, or Custom(..) for a bespoke check.
• max_lifetime caps how long a physical connection may live before it is retired at checkout, regardless of health.
• idle_timeout retires connections that have sat idle too long (down to min_idle, which is kept warm).
• Timeouts (wait_timeout, create_timeout, recycle_timeout) bound how long an acquire may block. The async pool enforces all three via deadpool’s Tokio runtime; the sync pool enforces wait_timeout natively (see SyncPoolConfig for the create/recycle caveat).

Lifecycle hooks (async pool only)

PoolConfig supports two async lifecycle hooks:

• after_connect runs once on every newly-opened connection (useful for SET search_path, prepared-statement warmup, etc.)
• before_acquire runs every time a connection is checked out (useful for session reset, telemetry, custom health checks)

use hyperdb_api::pool::{create_pool, PoolConfig, RecycleStrategy};
use hyperdb_api::CreateMode;

let config = PoolConfig::new("localhost:7483", "example.hyper")
    .create_mode(CreateMode::CreateIfNotExists)
    .max_size(16)
    .recycle(RecycleStrategy::None) // skip the per-checkout probe
    .after_connect(|conn| Box::pin(async move {
        conn.execute_command("SET search_path TO public").await?;
        Ok(())
    }));
let _pool = create_pool(config)?;

Structs

ConnectionManager

Connection pool manager for AsyncConnection.

ConnectionPool

A synchronous, r2d2-style pool of blocking Connections.

PoolConfig

Configuration for the async connection pool.

PoolStatus

A snapshot of ConnectionPool occupancy.

SyncPoolConfig

Configuration and builder for the synchronous ConnectionPool.

SyncPooledConnection

A connection checked out of a synchronous ConnectionPool.

Enums

RecycleStrategy

Strategy used by the async Pool to validate a connection when it is checked back out (recycled).

SyncRecycleStrategy

Strategy used by the synchronous ConnectionPool to validate a connection when it is checked out.

Functions

create_pool

Creates a new connection pool from configuration.

Type Aliases

AfterConnectHook

A hook that runs once on every newly-opened connection (after authentication and any database-creation handshake). Use it to set session variables, install statement caches, warm prepared statements, etc.

BeforeAcquireHook

A hook that runs every time a connection is checked out of the pool, before it is handed to the caller. Use it for per-acquire health checks, session resets, or telemetry.

HookFuture

Future returned by pool lifecycle hooks.

Pool

A pool of async connections to a Hyper database.

PooledConnection

A pooled connection wrapper.

RecycleCheck

A user-supplied async per-checkout health check for RecycleStrategy::Custom.

SyncRecycleCheck

A user-supplied synchronous per-checkout health check for SyncRecycleStrategy::Custom.