Struct Pool 

pub struct Pool { /* private fields */ }

A PostgreSQL connection pool.

Wraps deadpool-postgres with fail-fast acquire semantics, singleflight query coalescing, and optional read/write splitting.

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 primary pool.

Fail-fast: returns BsqlError::Pool immediately if no connections are available. Does not wait. Does not timeout. See CREDO principle #17.

pub fn is_pgbouncer(&self) -> bool

Whether PgBouncer was detected between the client and PostgreSQL.

pub fn has_replicas(&self) -> bool

Whether read replicas are configured.

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

Begin a new transaction.

Acquires a connection from the primary pool. BEGIN is sent lazily on the first query inside the transaction (see Transaction::ensure_begun). This eliminates one PG round-trip when the transaction is created.

If the transaction is committed or dropped without executing any queries, no BEGIN/COMMIT/ROLLBACK is sent at all and the connection returns to the pool cleanly.

Fail-fast: returns BsqlError::Pool immediately if no connections are available. See CREDO principle #17.

pub async fn query_stream( &self, sql: &str, params: &[&(dyn ToSql + 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. Rows arrive one at a time, avoiding buffering the entire result set in memory.

Fail-fast: returns BsqlError::Pool immediately if no connections are available. See CREDO principle #17.

This method is only available on Pool (not PoolConnection or Transaction) because the stream must own the connection for its entire lifetime.

pub async fn warmup(&self, sqls: &[&str]) -> BsqlResult<()>

Pre-prepare SQL statements on a connection from the pool.

Acquires one connection and calls prepare_cached for each SQL string. This populates the connection’s statement cache so the first real query on that connection pays zero PREPARE overhead.

Call this once after creating the pool with the SQL strings your application uses. The easiest source is your query!() calls:

pool.warmup(&[
    "SELECT id, login FROM users WHERE id = $1",
    "UPDATE tickets SET status = $1 WHERE id = $2",
]).await?;

Best-effort: if the pool is exhausted or a PREPARE fails (e.g. table was dropped), the error is returned but partial warmup of earlier statements still takes effect.

Calling warmup with an empty slice is a no-op.

pub fn status(&self) -> PoolStatus

Current pool status: available and total connections.

Trait Implementations

impl Debug for Pool

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

Formats the value using the given formatter.

impl Executor for Pool

type Rows = Arc<[Row]>

Row container returned by query_raw / query_raw_readonly.

async fn query_raw( &self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> BsqlResult<Arc<[Row]>>

Execute a query and return all rows.

async fn query_raw_readonly( &self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> BsqlResult<Arc<[Row]>>

Execute a read-only query. Routes to replicas when available.

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

Execute a query and return the number of affected rows.