Struct PooledConnection 

pub struct PooledConnection { /* private fields */ }

A pooled connection handle.

Use PooledConnection::release for deterministic reset+return behavior. If dropped without release(), the pool performs best-effort bounded async cleanup; on any uncertainty it destroys the connection (fail-closed).

Implementations

impl PooledConnection

pub fn get(&self) -> PgResult<&PgConnection>

Get a shared reference to the underlying connection.

Returns an error if the connection has already been released.

pub fn get_mut(&mut self) -> PgResult<&mut PgConnection>

Get a mutable reference to the underlying connection.

Returns an error if the connection has already been released.

pub fn cancel_token(&self) -> PgResult<CancelToken>

Get a token to cancel the currently running query.

pub async fn release(self)

Deterministic connection cleanup and pool return.

This is the correct way to return a connection to the pool. COMMITs the transaction (which auto-resets transaction-local RLS session variables) and returns the connection to the pool with prepared statement caches intact.

If cleanup fails, the connection is destroyed (not returned to pool).

Usage

let mut conn = pool.acquire_with_rls(ctx).await?;
let result = conn.fetch_all_cached(&cmd).await;
conn.release().await; // COMMIT + return to pool
result

pub async fn begin(&mut self) -> PgResult<()>

Begin an explicit transaction on this pooled connection.

Use this when you need multi-statement atomicity beyond the implicit transaction created by acquire_with_rls().

Example

let mut conn = pool.acquire_with_rls(ctx).await?;
conn.begin().await?;
conn.execute(&insert1).await?;
conn.execute(&insert2).await?;
conn.commit().await?;
conn.release().await;

pub async fn commit(&mut self) -> PgResult<()>

Commit the current transaction. Makes all changes since begin() permanent.

pub async fn rollback(&mut self) -> PgResult<()>

Rollback the current transaction. Discards all changes since begin().

pub async fn savepoint(&mut self, name: &str) -> PgResult<()>

Create a named savepoint within the current transaction. Use rollback_to() to return to this savepoint.

pub async fn rollback_to(&mut self, name: &str) -> PgResult<()>

Rollback to a previously created savepoint. Discards changes since the savepoint, but keeps the transaction open.

pub async fn release_savepoint(&mut self, name: &str) -> PgResult<()>

Release a savepoint (free resources). After release, the savepoint cannot be rolled back to.

pub async fn pipeline_ast( &mut self, cmds: &[Qail], ) -> PgResult<Vec<Vec<Vec<Option<Vec<u8>>>>>>

Execute multiple QAIL commands in a single PG pipeline round-trip.

Sends all queries as Parse+Bind+Execute in one write, receives all responses in one read. Returns raw column data per query per row.

This is the fastest path for batch operations — amortizes TCP overhead across N queries into a single syscall pair.

pub async fn explain_estimate( &mut self, cmd: &Qail, ) -> PgResult<Option<ExplainEstimate>>

Run EXPLAIN (FORMAT JSON) on a Qail command and return cost estimates.

Uses simple_query under the hood — no additional round-trips beyond the single EXPLAIN statement. Returns None if parsing fails or the EXPLAIN output is unexpected.

pub async fn listen(&mut self, channel: &str) -> PgResult<()>

Subscribe to a PostgreSQL notification channel.

Delegates to PgConnection::listen.

pub async fn unlisten(&mut self, channel: &str) -> PgResult<()>

Unsubscribe from a PostgreSQL notification channel.

Delegates to PgConnection::unlisten.

pub async fn unlisten_all(&mut self) -> PgResult<()>

Unsubscribe from all notification channels.

Delegates to PgConnection::unlisten_all.

pub async fn recv_notification(&mut self) -> PgResult<Notification>

Wait for the next notification, blocking until one arrives.

Delegates to PgConnection::recv_notification. Useful for dedicated LISTEN connections in background tasks.

impl PooledConnection

pub async fn fetch_all_uncached(&mut self, cmd: &Qail) -> PgResult<Vec<PgRow>>

Execute a QAIL command and fetch all rows (UNCACHED). Returns rows with column metadata for JSON serialization.

pub async fn query_raw_with_params( &mut self, sql: &str, params: &[Option<Vec<u8>>], ) -> PgResult<Vec<Vec<Option<Vec<u8>>>>>

Execute raw SQL with bind parameters and return raw row data.

Uses the Extended Query Protocol so parameters are never interpolated into the SQL string. Intended for EXPLAIN or other SQL that can’t be represented as a Qail AST but still needs parameterized execution.

Returns raw column bytes; callers must decode as needed.

pub async fn copy_export(&mut self, cmd: &Qail) -> PgResult<Vec<Vec<String>>>

Export data using AST-native COPY TO STDOUT and collect parsed rows.

pub async fn copy_export_stream_raw<F, Fut>( &mut self, cmd: &Qail, on_chunk: F, ) -> PgResult<()>

where F: FnMut(Vec<u8>) -> Fut, Fut: Future<Output = PgResult<()>>,

Stream AST-native COPY TO STDOUT chunks with bounded memory usage.

pub async fn copy_export_stream_rows<F>( &mut self, cmd: &Qail, on_row: F, ) -> PgResult<()>

where F: FnMut(Vec<String>) -> PgResult<()>,

Stream AST-native COPY TO STDOUT rows with bounded memory usage.

pub async fn copy_export_table( &mut self, table: &str, columns: &[String], ) -> PgResult<Vec<u8>>

Export a table using COPY TO STDOUT and collect raw bytes.

pub async fn copy_export_table_stream<F, Fut>( &mut self, table: &str, columns: &[String], on_chunk: F, ) -> PgResult<()>

where F: FnMut(Vec<u8>) -> Fut, Fut: Future<Output = PgResult<()>>,

Stream a table export using COPY TO STDOUT with bounded memory usage.

pub async fn fetch_all_uncached_with_format( &mut self, cmd: &Qail, result_format: ResultFormat, ) -> PgResult<Vec<PgRow>>

Execute a QAIL command and fetch all rows (UNCACHED) with explicit result format.

pub async fn fetch_all_fast(&mut self, cmd: &Qail) -> PgResult<Vec<PgRow>>

Execute a QAIL command and fetch all rows (FAST VERSION). Uses native AST-to-wire encoding and optimized recv_with_data_fast. Skips column metadata for maximum speed.

pub async fn fetch_all_fast_with_format( &mut self, cmd: &Qail, result_format: ResultFormat, ) -> PgResult<Vec<PgRow>>

Execute a QAIL command and fetch all rows (FAST VERSION) with explicit result format.

pub async fn fetch_all_cached(&mut self, cmd: &Qail) -> PgResult<Vec<PgRow>>

Execute a QAIL command and fetch all rows (CACHED). Uses prepared statement caching: Parse+Describe on first call, then Bind+Execute only on subsequent calls with the same SQL shape. This matches PostgREST’s behavior for fair benchmarks.

pub async fn fetch_all_cached_with_format( &mut self, cmd: &Qail, result_format: ResultFormat, ) -> PgResult<Vec<PgRow>>

Execute a QAIL command and fetch all rows (CACHED) with explicit result format.

pub async fn fetch_typed<T: QailRow>(&mut self, cmd: &Qail) -> PgResult<Vec<T>>

Execute a QAIL command and decode rows into typed structs (CACHED, text format).

pub async fn fetch_typed_with_format<T: QailRow>( &mut self, cmd: &Qail, result_format: ResultFormat, ) -> PgResult<Vec<T>>

Execute a QAIL command and decode rows into typed structs with explicit result format.

Use ResultFormat::Binary for binary wire values; row decoders should use metadata-aware helpers like PgRow::try_get() / try_get_by_name().

pub async fn fetch_one_typed<T: QailRow>( &mut self, cmd: &Qail, ) -> PgResult<Option<T>>

Execute a QAIL command and decode one typed row (CACHED, text format).

pub async fn fetch_one_typed_with_format<T: QailRow>( &mut self, cmd: &Qail, result_format: ResultFormat, ) -> PgResult<Option<T>>

Execute a QAIL command and decode one typed row with explicit result format.

pub async fn fetch_all_with_rls( &mut self, cmd: &Qail, rls_sql: &str, ) -> PgResult<Vec<PgRow>>

Execute a QAIL command with RLS context in a SINGLE roundtrip.

Pipelines the RLS setup (BEGIN + set_config) and the query (Parse/Bind/Execute/Sync) into one write_all syscall. PG processes messages in order, so the BEGIN + set_config completes before the query executes — security is preserved.

Wire layout:

[SimpleQuery: "BEGIN; SET LOCAL...; SELECT set_config(...)"]
[Parse (if cache miss)]
[Describe (if cache miss)]
[Bind]
[Execute]
[Sync]

Response processing: consume 2× ReadyForQuery (SimpleQuery + Sync).

pub async fn fetch_all_with_rls_with_format( &mut self, cmd: &Qail, rls_sql: &str, result_format: ResultFormat, ) -> PgResult<Vec<PgRow>>

Execute a QAIL command with RLS context in a SINGLE roundtrip with explicit result format.

Trait Implementations

impl Drop for PooledConnection

fn drop(&mut self)

Executes the destructor for this type.