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

Caching

PoolConnection contains cache set of Statement to speed up regular used sql queries. By default when calling Execute::execute on a StatementNamed the pool connection does nothing and function the same as a regular Client. In order to utilize the cache caller must execute the named statement through ExecuteMut::execute_mut. This method call will look up local statement cache hand out a copy of in the type of Arc<Statement>. If no copy is found in the cache pool connection will prepare a new statement and insert it into the cache.

• When to use caching or not:

• query statement repeatedly called intensely can benefit from cache.
• query statement with low latency requirement can benefit from upfront cached.
• rare query statement can benefit from no caching by reduce resource usage from the server side. For low latency of rare query consider use Statement::unnamed as alternative.

Implementations

impl PoolConnection<'_>

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

function the same as Client::transaction

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, Execute};

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

    "SELECT *".execute(&conn).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.
    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 = "SELECT *".execute(&conn.consume());

    // 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 = "SELECT *".execute(&conn);

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

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

    // 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<'c, 's> ExecuteMut<'c, PoolConnection<'_>> for StatementNamed<'s>

where 's: 'c,

type ExecuteMutOutput = StatementCacheFuture<'c>

type QueryMutOutput = <StatementNamed<'s> as ExecuteMut<'c, PoolConnection<'_>>>::ExecuteMutOutput

fn execute_mut(self, cli: &'c mut PoolConnection<'_>) -> Self::ExecuteMutOutput

fn query_mut(self, cli: &'c mut PoolConnection<'_>) -> Self::QueryMutOutput

impl Prepare for PoolConnection<'_>

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

fn _get_type_blocking(&self, oid: Oid) -> Result<Type, Error>

impl Query for PoolConnection<'_>

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

where S: Encode,

encode statement and params and send it to client driver

fn _query<S>( &self, stmt: S, ) -> Result<<S::Output as IntoResponse>::Response, Error>

where S: Encode,

query with statement and dynamic typed params.