Struct xitca_postgres::pool::PoolConnection

pub struct PoolConnection<'a> { /* private fields */ }

a RAII type for connection. it manages the lifetime of connection and it’s Statement cache. a set of public is exposed to interact with them.

Implementations

impl<'p> PoolConnection<'p>

pub async fn prepare( &self, query: &str, types: &[Type], ) -> Result<StatementGuarded<'_, Self>, Error>

function the same as Client::prepare

pub async fn prepare_cache( &mut self, query: &str, types: &[Type], ) -> Result<Arc<Statement>, Error>

function like Client::prepare with some behavior difference:

• statement will be cached for future reuse.
• statement type is Arc<Statement> smart pointer

• When to use cached prepare or plain prepare:

• query repeatedly called intensely can benefit from cached statement.
• query with low latency requirement can benefit from upfront cached statement.
• rare query can use plain prepare to reduce resource usage from the server side.

pub fn query<'a, S>( &self, stmt: S, params: &[&(dyn ToSql + Sync)], ) -> Result<S::RowStream<'a>, Error>

where S: Encode + IntoStream + 'a,

function the same as Client::query

pub fn query_raw<'a, S, I>( &self, stmt: S, params: I, ) -> Result<S::RowStream<'a>, Error>

where S: Encode + IntoStream + 'a, I: AsParams,

function the same as Client::query_raw

pub fn execute<S>( &self, stmt: S, params: &[&(dyn ToSql + Sync)], ) -> ExecuteFuture

where S: Encode,

function the same as Client::execute

pub fn execute_raw<S, I>(&self, stmt: S, params: I) -> ExecuteFuture

where S: Encode, I: AsParams,

function the same as Client::execute_raw

pub fn query_simple( &self, stmt: &str, ) -> Result<<&str as IntoStream>::RowStream<'_>, Error>

function the same as Client::query_simple

pub fn execute_simple(&self, stmt: &str) -> ExecuteFuture

function the same as Client::execute_simple

pub fn query_unnamed<'a>( &'a self, stmt: &'a str, types: &'a [Type], params: &[&(dyn ToSql + Sync)], ) -> Result<<StatementUnnamed<'a, Self> as IntoStream>::RowStream<'a>, Error>

function the same as Client::query_unnamed

pub fn transaction( &mut self, ) -> impl Future<Output = Result<Transaction<'_, Self>, Error>> + Send

function the same as Client::transaction

pub fn pipeline<'a, B, const SYNC_MODE: bool>( &self, pipe: Pipeline<'a, B, SYNC_MODE>, ) -> Result<PipelineStream<'a>, Error>

where B: DerefMut<Target = BytesMut>,

function the same as Client::pipeline

pub fn copy_in( &mut self, stmt: &Statement, ) -> impl Future<Output = Result<CopyIn<'_, Self>, Error>> + Send

function the same as Client::copy_in

pub async fn copy_out(&self, stmt: &Statement) -> Result<CopyOut, Error>

function the same as Client::copy_out

pub fn consume(self) -> Self

a shortcut to move and take ownership of self. an important behavior of PoolConnection is it supports pipelining. eagerly drop it after usage can contribute to more queries being pipelined. especially before any await point.

Examples

use xitca_postgres::{pool::Pool, Error};

async fn example(pool: &Pool) -> Result<(), Error> {
    // get a connection from pool and start a query.
    let mut conn = pool.get().await?;

    conn.execute_simple("SELECT *").await?;
     
    // connection is kept across await point. making it unusable to other concurrent
    // callers to example function. and no pipelining will happen until it's released.
    let conn = conn;

    // start another query but this time consume ownership and when res is returned
    // connection is dropped and went back to pool.
    let res = conn.consume().execute_simple("SELECT *");

    // connection can't be used anymore in this scope but other concurrent callers
    // to example function is able to use it and if they follow the same calling
    // convention pipelining could happen and reduce syscall overhead.
    //
    // let res = conn.consume().execute_simple("SELECT *");

    // without connection the response can still be collected asynchronously
    res.await?;

    // therefore a good calling convention for independent queries could be:
    let mut conn = pool.get().await?;
    let res1 = conn.execute_simple("SELECT *");
    let res2 = conn.execute_simple("SELECT *");
    let res3 = conn.consume().execute_simple("SELECT *");

    // all three queries can be pipelined into a single write syscall. and possibly
    // even more can be pipelined after conn.consume() is called if there are concurrent
    // callers use the same connection.
     
    res1.await?;
    res2.await?;
    res3.await?;

    // it should be noted that pipelining is an optional crate feature for some potential
    // performance gain.
    // it's totally fine to ignore and use the apis normally with zero thought put into it.

    Ok(())
}

pub fn cancel_token(&self) -> Session

function the same as Client::cancel_token

Trait Implementations

impl ClientBorrowMut for PoolConnection<'_>

fn _borrow_mut(&mut self) -> &mut Client

impl Copy for PoolConnection<'_>

fn send_one_way<F>(&self, func: F) -> Result<(), Error>

where F: FnOnce(&mut BytesMut) -> Result<(), Error>,

impl Drop for PoolConnection<'_>

fn drop(&mut self)

Executes the destructor for this type.

impl Prepare for PoolConnection<'_>

fn _get_type( &self, oid: Oid, ) -> Pin<Box<dyn Future<Output = Result<Type, Error>> + Send + '_>>

fn _prepare( &self, query: &str, types: &[Type], ) -> impl Future<Output = Result<Statement, Error>> + Send

impl Query for PoolConnection<'_>

fn _send_encode_query<S, I>( &self, stmt: S, params: I, ) -> Result<Response, Error>

where S: Encode, I: AsParams,

encode statement and params and send it to client driver

fn _query<'a, S>( &self, stmt: S, params: &[&(dyn ToSql + Sync)], ) -> Result<S::RowStream<'a>, Error>

where S: Encode + IntoStream + 'a,

query with statement and dynamic typed params.

fn _query_raw<'a, S, I>( &self, stmt: S, params: I, ) -> Result<S::RowStream<'a>, Error>

where S: Encode + IntoStream + 'a, I: AsParams,

flexible version of Query::_query

fn _execute<S>(&self, stmt: S, params: &[&(dyn ToSql + Sync)]) -> ExecuteFuture

where S: Encode,

query that don’t return any row but number of rows affected by it

fn _execute_raw<S, I>(&self, stmt: S, params: I) -> ExecuteFuture

where S: Encode, I: AsParams,

flexible version of Query::_execute