Struct xitca_postgres::Client

pub struct Client { /* private fields */ }

Client is a handler type for Driver. it interacts with latter using channel and message for IO operation and de/encoding of postgres protocol in byte format.

Client expose a set of high level API to make the interaction represented in Rust function and types.

Lifetime

Client and Driver have a dependent lifetime where either side can trigger the other part to shutdown. From Client side it’s in the form of dropping ownership.

Examples

// connect to a database and spawn driver as async task
let (cli, drv) = Postgres::new(cfg).connect().await?;
let handle = tokio::spawn(drv.into_future());

// drop client after finished usage
drop(cli);

// client would notify driver to shutdown when it's dropped.
// await on the handle would return a Result of the shutdown outcome from driver side.  
let _ = handle.await.unwrap();

Implementations

impl Client

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

Creates a new prepared statement.

Prepared statements can be executed repeatedly, and may contain query parameters (indicated by $1, $2, etc), which are set when executed. Prepared statements can only be used with the connection that created them.

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

where S: Encode + IntoStream + 'a,

Executes a statement, returning an async stream of the resulting rows.

A statement may contain parameters, specified by $n, where n is the index of the parameter of the list provided, 1-indexed.

If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with Client::prepare.

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

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

The maximally flexible version of Client::query.

A statement may contain parameters, specified by $n, where n is the index of the parameter of the list provided, 1-indexed.

If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with Client::prepare.

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

where S: Encode,

Executes a statement, returning the number of rows modified.

A statement may contain parameters, specified by $n, where n is the index of the parameter of the list provided, 1-indexed.

If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with Client::prepare.

If the statement does not modify any rows (e.g. SELECT), 0 is returned.

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

where S: Encode, I: AsParams,

The maximally flexible version of Client::execute.

A statement may contain parameters, specified by $n, where n is the index of the parameter of the list provided, 1-indexed.

If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with Client::prepare.

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

Executes a sequence of SQL statements using the simple query protocol, returning async stream of rows.

Statements should be separated by semicolons. If an error occurs, execution of the sequence will stop at that point. The simple query protocol returns the values in rows as strings rather than in their binary encodings, so the associated row type doesn’t work with the FromSql trait. Rather than simply returning a list of the rows, this method returns a list of an enum which indicates either the completion of one of the commands, or a row of data. This preserves the framing between the separate statements in the request.

Warning

Prepared statements should be use for any query which contains user-specified data, as they provided the functionality to safely embed that data in the request. Do not form statements via string concatenation and pass them to this method!

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

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>

Embed prepare statement to the query request itself. Meaning query would finish in one round trip to database. However it should also be noted that the client type must be referenced during the whole progress and associated client must be kept around util streaming is finished.

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

start a transaction

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

Executes a COPY FROM STDIN statement, returning a sink used to write the copy data.

PostgreSQL does not support parameters in COPY statements, so this method does not take any. The copy must be explicitly completed via CopyIn::finish. If it is not, the copy will be aborted.

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

Executes a COPY TO STDOUT statement, returning async stream of the resulting data.

PostgreSQL does not support parameters in COPY statements, so this method does not take any.

pub fn cancel_token(&self) -> Session

Constructs a cancellation token that can later be used to request cancellation of a query running on the connection associated with this client.

pub fn closed(&self) -> bool

a lossy hint of running state of io driver. an io driver shutdown can happen at the same time this api is called.

pub fn typeinfo(&self) -> Option<Statement>

pub fn set_typeinfo(&self, statement: &Statement)

pub fn typeinfo_composite(&self) -> Option<Statement>

pub fn set_typeinfo_composite(&self, statement: &Statement)

pub fn typeinfo_enum(&self) -> Option<Statement>

pub fn set_typeinfo_enum(&self, statement: &Statement)

pub fn type_(&self, oid: Oid) -> Option<Type>

pub fn set_type(&self, oid: Oid, type_: &Type)

pub fn clear_type_cache(&self)

Clears the client’s type information cache.

When user-defined types are used in a query, the client loads their definitions from the database and caches them for the lifetime of the client. If those definitions are changed in the database, this method can be used to flush the local cache and allow the new, updated definitions to be loaded.

impl Client

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>,

execute the pipeline.

Trait Implementations

impl ClientBorrowMut for Client

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

impl Copy for Client

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

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

impl Drop for Client

fn drop(&mut self)

Executes the destructor for this type.

impl Prepare for Client

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 Client

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