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. when calling Execute::execute on a StatementNamed with &PoolConnection the pool connection does nothing special and function the same as a regular Client. In order to utilize the cache caller must execute the named statement with &mut PoolConnection. With a mutable reference of pool connection it will do local cache look up for statement and hand out one in the type of Statement if any found. If no copy is found in the cache pool connection will prepare a new statement and insert it into the cache.

Examples

let mut conn = pool.get().await?;
// prepare a statement without caching
Statement::named("SELECT 1", &[]).execute(&conn).await?;
// prepare a statement with caching from conn.
Statement::named("SELECT 1", &[]).execute(&mut conn).await?;

• 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 cache.
• rare query statement can benefit from no caching by reduce resource usage from the server side. For low latency of rare query consider use StatementNamed::bind as alternative.

Implementations

impl PoolConnection<'_>

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

function the same as Client::transaction

pub fn transaction_owned( self, ) -> impl Future<Output = Result<Transaction<Self>, Error>> + Send

owned version of PoolConnection::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> Execute<&'c mut PoolConnection<'_>> for StatementNamed<'s>

where 's: 'c,

type ExecuteOutput = StatementCacheFuture<'c>

outcome of execute. used for single time database response: number of rows affected by execution for example.

type QueryOutput = <StatementNamed<'s> as Execute<&'c mut PoolConnection<'_>>>::ExecuteOutput

outcome of query. used for repeated database response: database rows for example

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

define how a statement is executed with single time response

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

define how a statement is queried with repeated response

impl<'c, 's, P> Execute<&'c mut PoolConnection<'_>> for StatementQuery<'s, P>

where P: AsParams + Send + 'c, 's: 'c,

Available on non-crate feature nightly only.

type ExecuteOutput = Pin<Box<dyn Future<Output = Result<RowAffected, Error>> + Send + 'c>>

outcome of execute. used for single time database response: number of rows affected by execution for example.

type QueryOutput = Pin<Box<dyn Future<Output = Result<GenericRowStream<Arc<[Column]>, Typed>, Error>> + Send + 'c>>

outcome of query. used for repeated database response: database rows for example

fn execute(self, conn: &'c mut PoolConnection<'_>) -> Self::ExecuteOutput

define how a statement is executed with single time response

fn query(self, conn: &'c mut PoolConnection<'_>) -> Self::QueryOutput

define how a statement is queried with repeated response

impl Prepare for PoolConnection<'_>

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

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.