Struct Pool 

pub struct Pool { /* private fields */ }

A PostgreSQL connection pool.

Created via Pool::connect or Pool::builder. The pool manages a set of connections, automatically acquires/releases them for each query, and supports optional read/write splitting with a replica.

Example

use bsql::Pool;

let pool = Pool::connect("postgres://user:pass@localhost/mydb").await?;

// Or configure via builder:
let pool = Pool::builder()
    .url("postgres://user:pass@localhost/mydb")
    .lifetime_secs(900)
    .timeout_secs(5)
    .build()
    .await?;

Implementations

impl Pool

pub async fn connect(url: &str) -> BsqlResult<Self>

Connect to PostgreSQL using a connection URL.

Format: postgres://user:password@host:port/dbname

pub fn builder() -> PoolBuilder

Create a pool builder for fine-grained configuration.

pub async fn acquire(&self) -> BsqlResult<PoolConnection>

Acquire a connection from the pool.

Fail-fast: returns BsqlError::Pool immediately if no connections are available (unless acquire_timeout is configured).

pub async fn begin(&self) -> BsqlResult<Transaction>

Begin a new transaction.

Acquires a connection and sends BEGIN immediately.

pub async fn query_stream( &self, sql: &str, sql_hash: u64, params: &[&(dyn Encode + Sync)], ) -> BsqlResult<QueryStream>

Execute a query and return a stream of rows.

Acquires a connection from the pool and returns a QueryStream that holds the connection alive until the stream is consumed or dropped.

Uses true PG-level streaming via Execute(max_rows=64). Only 64 rows are in memory at a time. The stream fetches additional chunks on demand via the PortalSuspended / re-Execute protocol.

pub fn set_warmup_sqls(&self, sqls: &[&str])

Set the SQL statements to pre-PREPARE on new connections.

Each SQL string is PREPAREd on new connections before they are returned from acquire(). This eliminates first-use Parse overhead for hot queries.

Warmup errors are silently ignored — a bad warmup SQL does not prevent the connection from being usable.

pub fn status(&self) -> PoolStatus

Pool status metrics: idle, active, open, and max_size.

Returns detailed pool utilization metrics from the driver.

pub async fn close(&self)

Gracefully close the pool (and replica pool if configured).

No new connections can be acquired after this call. All idle connections are closed immediately. Active connections are closed when returned to the pool.

pub fn is_closed(&self) -> bool

Whether the pool has been closed.

pub fn has_replica(&self) -> bool

Whether a read replica pool is configured.

pub fn is_uds(&self) -> bool

Whether this pool uses sync connections via Unix domain sockets.

When true, the pool automatically uses SyncConnection (blocking I/O) internally, eliminating async overhead for sub-microsecond UDS I/O. The user API is identical — this is purely a performance optimization.

pub async fn for_each_raw<F>( &self, sql: &str, sql_hash: u64, params: &[&(dyn Encode + Sync)], readonly: bool, f: F, ) -> BsqlResult<()>

where F: FnMut(PgDataRow<'_>) -> BsqlResult<()>,

Process each row directly from the wire buffer via a closure.

Acquires a connection, calls Connection::for_each, and releases. Zero arena allocation — the closure reads columns directly from the DataRow message bytes.

When readonly is true and a replica pool is configured, routes to the replica pool; otherwise uses the primary.

Trait Implementations

impl Clone for Pool

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Pool

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Executor for Pool

async fn query_raw( &self, sql: &str, sql_hash: u64, params: &[&(dyn Encode + Sync)], ) -> BsqlResult<OwnedResult>

Execute a query and return all rows.

async fn query_raw_readonly( &self, sql: &str, sql_hash: u64, params: &[&(dyn Encode + Sync)], ) -> BsqlResult<OwnedResult>

Execute a read-only query. May route to replicas in the future.

async fn execute_raw( &self, sql: &str, sql_hash: u64, params: &[&(dyn Encode + Sync)], ) -> BsqlResult<u64>

Execute a query and return the number of affected rows.