Struct Pool

Source

pub struct Pool { /* private fields */ }

Expand description

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")?;

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

Implementations§

Source §

impl Pool

Source

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

Connect to PostgreSQL using a connection URL.

Creates the pool (parses URL, allocates pool structures). Actual TCP/UDS connections are established lazily on first acquire().

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

Source

pub fn builder() -> PoolBuilder

Create a pool builder for fine-grained configuration.

Source

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).

Source

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

Begin a new transaction.

Acquires a connection and sends BEGIN immediately.

Source

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.

Source

pub fn set_warmup_sqls<S: Into<Box<str>>>( &self, sqls: impl IntoIterator<Item = S>, )

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.

Source

pub async fn raw_query(&self, sql: &str) -> BsqlResult<Vec<RawRow>>

Execute arbitrary SQL and return text rows.

Uses PostgreSQL’s simple query protocol — all values returned as strings. This bypasses bsql’s compile-time SQL validation entirely.

Use for DDL, ad-hoc queries, migrations, or the rare dynamic SQL that cannot be expressed via query!. For type-safe queries, use query!.

Source

pub async fn raw_execute(&self, sql: &str) -> BsqlResult<()>

Execute arbitrary SQL without returning rows.

Uses PostgreSQL’s simple query protocol. Useful for DDL (CREATE TABLE, ALTER, DROP), SET commands, or any statement where you don’t need results.

Source

pub async fn copy_in<'a, I>( &self, table: &str, columns: &[&str], rows: I, ) -> BsqlResult<u64>
where I: IntoIterator<Item = &'a str>,

Bulk copy data INTO a table from an iterator of text rows.

Each row is a tab-separated string (TSV format, matching PostgreSQL’s default COPY text format). Returns the number of rows copied.

This is 10-100x faster than individual INSERTs for bulk data loading.

§Example

let rows = vec!["alice\talice@example.com", "bob\tbob@example.com"];
let count = pool.copy_in("users", &["name", "email"], rows.iter().map(|s| s.as_str())).await?;

Source

pub async fn copy_out<W: Write>( &self, query: &str, writer: &mut W, ) -> BsqlResult<u64>

Bulk copy data OUT of a table or query result to a writer.

Data is written in PostgreSQL’s text format (tab-separated columns, newline-terminated rows). Returns the number of rows copied.

§Example

let mut buf = Vec::new();
let count = pool.copy_out("SELECT name, email FROM users", &mut buf).await?;

Source

pub fn status(&self) -> PoolStatus

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

Returns detailed pool utilization metrics from the driver.

Source

pub 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.

Source

pub fn is_closed(&self) -> bool

Whether the pool has been closed.

Source

pub fn has_replica(&self) -> bool

Whether a read replica pool is configured.

Source

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.

Source

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.