Struct PooledConnection 

pub struct PooledConnection { /* private fields */ }

A connection checked out from the pool.

When dropped, the connection is automatically returned to the pool (unless it has been marked as broken). The after_release callback runs before the connection re-enters the idle queue.

Implementations

impl PooledConnection

pub fn mark_broken(&mut self)

Mark this connection as broken. It will be discarded on drop instead of being returned to the pool.

Methods from Deref<Target = Connection>

pub fn cancel_token(&self) -> CancelToken

Get a cancel token for this connection.

The token can be cloned and sent to another task to cancel a running query. See CancelToken for details.

pub fn config(&self) -> &Config

Returns true if the connection is using TLS. Returns the configuration used for this connection.

pub fn connected_host(&self) -> &str

Returns the host this connection is connected to.

pub fn connected_port(&self) -> u16

Returns the port this connection is connected to.

pub fn is_tls(&self) -> bool

pub fn is_unix(&self) -> bool

Returns true if connected via Unix domain socket.

pub fn process_id(&self) -> i32

The server process ID for this connection.

pub fn query_timeout(&self) -> Option<Duration>

Returns the configured query timeout, if any.

pub fn is_broken(&self) -> bool

Returns true if the connection has been marked broken by a timeout.

A broken connection should be discarded — the server state is indeterminate after a cancelled query.

pub fn transaction_status(&self) -> TransactionStatus

Current transaction status.

pub fn set_instrumentation(&mut self, instr: Arc<dyn Instrumentation>)

Install an Instrumentation impl on this connection. Replaces any previous installation.

pub fn instrumentation(&self) -> &Arc<dyn Instrumentation>

Public accessor used by downstream macro helpers (e.g. sntl’s __priv::emit_query_macro). Returns the shared Arc so callers can emit Sentinel-level events through the same trait.

pub async fn copy_in(&mut self, sql: &str) -> Result<CopyIn<'_>>

Start a COPY IN operation for bulk data loading.

pub async fn copy_out(&mut self, sql: &str) -> Result<CopyOut<'_>>

Start a COPY OUT operation for bulk data export.

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

Subscribe to LISTEN/NOTIFY on a channel.

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

Unsubscribe from a channel.

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

Unsubscribe from all channels.

pub async fn notify(&mut self, channel: &str, payload: &str) -> Result<()>

Send a notification on a channel.

pub async fn wait_for_notification(&mut self) -> Result<Notification>

Wait for the next LISTEN/NOTIFY notification.

Blocks until a notification arrives on any subscribed channel.

Emits a crate::Event::Notification event on success.

Note: in-band NoticeResponse messages during regular queries are not emitted as Notice events — the driver’s query path doesn’t yet handle them gracefully. Startup-time notices log via tracing::debug only (instrumentation isn’t installed until after startup).

pub fn pipeline(&self) -> PipelineBatch

Create a pipeline batch for executing multiple queries in a single round-trip.

Use execute_pipeline() to send the batch.

pub async fn execute_pipeline( &mut self, batch: PipelineBatch, ) -> Result<Vec<QueryResult>>

Execute a pipeline batch, returning results for each query.

pub async fn bind_portal( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result<Portal>

Create a server-side portal (cursor) for incremental row fetching.

Portals only work inside transactions. The portal borrows the connection state, so no concurrent queries while a portal is open.

Example

conn.begin().await?;
let portal = conn.bind_portal("SELECT * FROM big_table", &[]).await?;
let batch = conn.query_portal(&portal, 100).await?;
conn.close_portal(portal).await?;
conn.commit().await?;

pub async fn query_portal( &mut self, portal: &Portal, max_rows: i32, ) -> Result<Vec<Row>>

Fetch up to max_rows rows from a portal.

Returns an empty Vec when the cursor is exhausted. Use max_rows = 0 to fetch all remaining rows.

pub async fn close_portal(&mut self, portal: Portal) -> Result<()>

Close a portal on the server, freeing resources.

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

Prepare a statement on the server using extended query protocol.

Returns a Statement with parameter types and column descriptions.

Emits PrepareStart before the wire round-trip and PrepareFinish on success. cache_hit is always false today because prepare() always sends Parse; a future task that wires automatic cache lookup will toggle that field without breaking the API.

pub fn register_statement(&mut self, name: &str, statement: Statement)

Register a prepared statement in the Tier 1 cache.

pub fn cache_metrics(&self) -> &CacheMetrics

Get statement cache metrics.

pub async fn query( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result<Vec<Row>>

Execute a query that returns rows.

Parameters are encoded in binary format.

let rows = conn.query("SELECT * FROM users WHERE id = $1", &[&42i32]).await?;

pub async fn query_one( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result<Row>

Execute a query that returns a single row.

Returns an error if no rows are returned.

pub async fn query_opt( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result<Option<Row>>

Execute a query that returns an optional single row.

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

Execute a non-SELECT query (INSERT, UPDATE, DELETE, etc.).

Returns the number of rows affected.

pub async fn query_with_timeout( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], timeout: Duration, ) -> Result<Vec<Row>>

Execute a query with a timeout.

If the query does not complete within timeout, a cancel request is sent to the server and the connection is marked as broken.

pub async fn execute_with_timeout( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], timeout: Duration, ) -> Result<u64>

Execute a non-SELECT query with a timeout.

If the query does not complete within timeout, a cancel request is sent to the server and the connection is marked as broken.

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

Execute a simple query (no parameters, text protocol).

Returns row data (in text format) and command completions. Useful for DDL statements, multi-statement queries, and queries where you don’t need binary-decoded typed values.

use sentinel_driver::SimpleQueryMessage;

let messages = conn.simple_query("SELECT 1 AS n; SELECT 'hello' AS greeting").await?;
for msg in &messages {
    match msg {
        SimpleQueryMessage::Row(row) => {
            println!("value: {:?}", row.get(0));
        }
        SimpleQueryMessage::CommandComplete(n) => {
            println!("rows: {n}");
        }
    }
}

pub async fn query_typed( &mut self, sql: &str, params: &[(&(dyn ToSql + Sync), Oid)], ) -> Result<Vec<Row>>

Execute a query with inline parameter types, skipping the prepare step.

Instead of a separate Prepare round-trip, the parameter types are specified directly in the Parse message. This saves one round-trip compared to query() at the cost of requiring the caller to specify types explicitly.

use sentinel_driver::Oid;

let rows = conn.query_typed(
    "SELECT $1::int4 + $2::int4 AS sum",
    &[(&1i32, Oid::INT4), (&2i32, Oid::INT4)],
).await?;

pub async fn query_typed_one( &mut self, sql: &str, params: &[(&(dyn ToSql + Sync), Oid)], ) -> Result<Row>

Execute a typed query that returns a single row.

pub async fn query_typed_opt( &mut self, sql: &str, params: &[(&(dyn ToSql + Sync), Oid)], ) -> Result<Option<Row>>

Execute a typed query that returns an optional single row.

pub async fn execute_typed( &mut self, sql: &str, params: &[(&(dyn ToSql + Sync), Oid)], ) -> Result<u64>

Execute a typed non-SELECT query, returning rows affected.

pub async fn query_stream( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result<RowStream<'_>>

Execute a streaming query that returns rows one at a time.

Unlike query() which materializes all rows in memory, this returns a RowStream that yields rows lazily. Ideal for large result sets.

The stream holds an exclusive borrow of the connection — no other queries can run until the stream is dropped or fully consumed.

let mut stream = conn.query_stream("SELECT * FROM users", &[]).await?;
while let Some(row) = stream.next().await? {
    let name: String = row.get(0);
}

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

Begin a transaction with default settings.

pub async fn begin_with(&mut self, config: TransactionConfig) -> Result<()>

Begin a transaction with custom settings.

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

Commit the current transaction.

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

Rollback the current transaction.

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

Create a savepoint.

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

Rollback to a savepoint.

Trait Implementations

impl Deref for PooledConnection

type Target = Connection

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for PooledConnection

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for PooledConnection

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl GenericClient for PooledConnection

async fn query( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result<Vec<Row>>

Execute a query that returns rows.

async fn query_one( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result<Row>

Execute a query that returns a single row.

async fn query_opt( &mut self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result<Option<Row>>

Execute a query that returns an optional single row.

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

Execute a non-SELECT query, returning rows affected.

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

Execute a simple query (text protocol, no parameters).

async fn query_typed( &mut self, sql: &str, params: &[(&(dyn ToSql + Sync), Oid)], ) -> Result<Vec<Row>>

Execute a typed query (skips the prepare round-trip).

async fn query_typed_one( &mut self, sql: &str, params: &[(&(dyn ToSql + Sync), Oid)], ) -> Result<Row>

Execute a typed query that returns a single row.

async fn query_typed_opt( &mut self, sql: &str, params: &[(&(dyn ToSql + Sync), Oid)], ) -> Result<Option<Row>>

Execute a typed query that returns an optional row.

async fn execute_typed( &mut self, sql: &str, params: &[(&(dyn ToSql + Sync), Oid)], ) -> Result<u64>

Execute a typed non-SELECT, returning rows affected.

async fn execute_pipeline( &mut self, batch: PipelineBatch, ) -> Result<Vec<QueryResult>>

Run a pre-built PipelineBatch in one round-trip.