Struct xitca_postgres::pipeline::Pipeline

pub struct Pipeline<'a, B = Owned, const SYNC_MODE: bool = true> { /* private fields */ }

A pipelined sql query type. It lazily batch queries into local buffer and try to send it with the least amount of syscall when pipeline starts.

Examples

use xitca_postgres::{AsyncLendingIterator, Client, pipeline::Pipeline};

async fn pipeline(client: &Client) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // prepare a statement that will be called repeatedly.
    // it can be a collection of statements that will be called in iteration.
    let statement = client.prepare("SELECT * FROM public.users", &[]).await?;

    // create a new pipeline.
    let mut pipe = Pipeline::new();

    // pipeline can encode multiple queries.
    pipe.query(statement.as_ref(), &[])?;
    pipe.query_raw::<[i32; 0]>(statement.as_ref(), [])?;

    // execute the pipeline and on success a streaming response will be returned.
    let mut res = client.pipeline(pipe)?;

    // iterate through the query responses. the response order is the same as the order of
    // queries encoded into pipeline with Pipeline::query_xxx api.
    while let Some(mut item) = res.try_next().await? {
        // every query can contain streaming rows.
        while let Some(row) = item.try_next().await? {
            let _: u32 = row.get("id");
        }
    }

    Ok(())
}

Implementations

impl Pipeline<'_, Owned, true>

pub fn new() -> Self

start a new pipeline.

pipeline is sync by default. which means every query inside is considered separate binding and the pipeline is transparent to database server. the pipeline only happen on socket transport where minimal amount of syscall is needed.

for more relaxed Pipeline Mode see Pipeline::unsync api.

pub fn with_capacity(cap: usize) -> Self

start a new pipeline with given capacity. capacity represent how many queries will be contained by a single pipeline. a determined cap can possibly reduce memory reallocation when constructing the pipeline.

impl Pipeline<'_, Owned, false>

pub fn unsync() -> Self

start a new un-sync pipeline.

in un-sync mode pipeline treat all queries inside as one single binding and database server can see them as no sync point in between which can result in potential performance gain.

it behaves the same on transportation level as Pipeline::new where minimal amount of socket syscall is needed.

pub fn unsync_with_capacity(cap: usize) -> Self

start a new un-sync pipeline with given capacity. capacity represent how many queries will be contained by a single pipeline. a determined cap can possibly reduce memory reallocation when constructing the pipeline.

impl<'a> Pipeline<'_, Borrowed<'a>, true>

pub fn from_buf(buf: &'a mut BytesMut) -> Self

start a new borrowed pipeline. pipeline will use borrowed bytes buffer to store encode messages before sending it to database.

pipeline is sync by default. which means every query inside is considered separate binding and the pipeline is transparent to database server. the pipeline only happen on socket transport where minimal amount of syscall is needed.

for more relaxed Pipeline Mode see Pipeline::unsync_from_buf api.

pub fn with_capacity_from_buf(cap: usize, buf: &'a mut BytesMut) -> Self

start a new borrowed pipeline with given capacity. capacity represent how many queries will be contained by a single pipeline. a determined cap can possibly reduce memory reallocation when constructing the pipeline.

impl<'a> Pipeline<'_, Borrowed<'a>, false>

pub fn unsync_from_buf(buf: &'a mut BytesMut) -> Self

start a new borrowed un-sync pipeline.

in un-sync mode pipeline treat all queries inside as one single binding and database server can see them as no sync point in between which can result in potential performance gain.

it behaves the same on transportation level as Pipeline::from_buf where minimal amount of socket syscall is needed.

pub fn unsync_with_capacity_from_buf(cap: usize, buf: &'a mut BytesMut) -> Self

start a new borrowed un-sync pipeline with given capacity. capacity represent how many queries will be contained by a single pipeline. a determined cap can possibly reduce memory reallocation when constructing the pipeline.

impl<'a, B, const SYNC_MODE: bool> Pipeline<'a, B, SYNC_MODE>

where B: DerefMut<Target = BytesMut>,

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

pipelined version of Client::query and Client::execute

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

where I: AsParams,

pipelined version of Client::query_raw and Client::execute_raw