Struct PoolGuard 

pub struct PoolGuard { /* private fields */ }

A borrowed connection from the pool. Returns to the pool on drop.

If the connection is in a failed transaction state, broken, or marked for discard, it is dropped (decrements open_count) instead of returned.

PoolGuard dispatches query methods to either the async Connection or the sync SyncConnection depending on the underlying slot type. For sync connections, blocking I/O is wrapped in tokio::task::block_in_place.

Implementations

impl PoolGuard

pub fn mark_discard(&mut self)

Mark this connection for discard — it will NOT be returned to the pool on drop. The open_count is decremented and the TCP connection is closed.

Used by streaming queries that are dropped mid-iteration: the connection may be in an indeterminate protocol state (portal open, no ReadyForQuery) and cannot be safely reused.

pub async fn cancel(&self) -> Result<(), DriverError>

Cancel the currently running query on the underlying connection.

Opens a new TCP connection and sends a CancelRequest to PG. The cancel connection is closed immediately after.

pub fn pid(&self) -> i32

Get the backend process ID for this connection.

pub fn is_idle(&self) -> bool

Whether the connection is idle (not in a transaction).

pub fn is_in_transaction(&self) -> bool

Whether the connection is inside a transaction.

pub async fn query( &mut self, sql: &str, sql_hash: u64, params: &[&(dyn Encode + Sync)], arena: &mut Arena, ) -> Result<QueryResult, DriverError>

Execute a prepared query and return rows in arena-allocated storage.

pub async fn execute( &mut self, sql: &str, sql_hash: u64, params: &[&(dyn Encode + Sync)], ) -> Result<u64, DriverError>

Execute a query without result rows (INSERT/UPDATE/DELETE).

For sync UDS connections, calls execute_monolithic directly — the entire send+receive path is inlined in one function.

pub async fn execute_pipeline( &mut self, sql: &str, sql_hash: u64, param_sets: &[&[&(dyn Encode + Sync)]], ) -> Result<Vec<u64>, DriverError>

Execute the same statement N times with different params in one pipeline.

Sends all N Bind+Execute messages + one Sync. One round-trip for N operations. Returns the affected row count for each parameter set.

pub async fn simple_query(&mut self, sql: &str) -> Result<(), DriverError>

Execute a simple (unprepared) query.

pub async fn for_each<F>( &mut self, sql: &str, sql_hash: u64, params: &[&(dyn Encode + Sync)], f: F, ) -> Result<(), DriverError>

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

Process each row via a closure with zero-copy PgDataRow.

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

where F: FnMut(&[u8]) -> Result<(), DriverError>,

Process each DataRow as raw bytes — fastest path.

For sync UDS connections, calls for_each_raw_monolithic directly — the entire send+receive path is inlined in one function.

pub async fn query_streaming_start( &mut self, sql: &str, sql_hash: u64, params: &[&(dyn Encode + Sync)], chunk_size: i32, ) -> Result<(Arc<[ColumnDesc]>, bool), DriverError>

Start a streaming query. Only available on async connections.

Returns an error if called on a sync UDS connection (streaming requires the async protocol’s portal suspend/resume mechanism).

pub async fn streaming_send_execute( &mut self, chunk_size: i32, ) -> Result<(), DriverError>

Send Execute+Flush for a streaming query (2nd+ chunks).

pub async fn streaming_next_chunk( &mut self, arena: &mut Arena, all_col_offsets: &mut Vec<(usize, i32)>, ) -> Result<bool, DriverError>

Read the next chunk of rows from an in-progress streaming query.

pub fn is_sync(&self) -> bool

Whether this guard holds a sync (UDS) connection.

Useful for callers that need to know the connection type (e.g., to choose between streaming and non-streaming query paths).

Trait Implementations

impl Drop for PoolGuard

fn drop(&mut self)

Executes the destructor for this type.