Struct 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 fn transaction( &mut self, ) -> impl Future<Output = Result<Transaction<'_, Self>, Error>> + Send

start a transaction

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

owned version of Client::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.

Trait Implementations

impl ClientBorrow for Client

fn borrow_cli_ref(&self) -> &Client

impl ClientBorrowMut for Client

fn borrow_cli_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<'c> Execute<&'c Client> for &Path

Available on non-crate feature nightly only.

type ExecuteOutput = Pin<Box<dyn Future<Output = Result<u64, 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<Vec<Column>, NoTyped>, Error>> + Send + 'c>>

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

fn execute(self, cli: &'c Client) -> Self::ExecuteOutput

define how a statement is executed with single time response

fn query(self, cli: &'c Client) -> Self::QueryOutput

define how a statement is queried with repeated response

impl<'s> Execute<&Client> for &'s Statement

type ExecuteOutput = ResultFuture<RowAffected>

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

type QueryOutput = Ready<Result<GenericRowStream<&'s [Column], Typed>, Error>>

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

fn execute(self, cli: &Client) -> Self::ExecuteOutput

define how a statement is executed with single time response

fn query(self, cli: &Client) -> Self::QueryOutput

define how a statement is queried with repeated response

impl Execute<&Client> for &str

type ExecuteOutput = ResultFuture<RowAffected>

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

type QueryOutput = Ready<Result<GenericRowStream<Vec<Column>, NoTyped>, Error>>

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

fn execute(self, cli: &Client) -> Self::ExecuteOutput

define how a statement is executed with single time response

fn query(self, cli: &Client) -> Self::QueryOutput

define how a statement is queried with repeated response

impl<'c> Execute<&'c Client> for StatementNamed<'_>

type ExecuteOutput = ResultFuture<IntoGuarded<'c, Pin<Box<dyn Future<Output = Result<Statement, Error>> + Send + 'c>>, Client>>

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

type QueryOutput = <StatementNamed<'_> as Execute<&'c Client>>::ExecuteOutput

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

fn execute(self, cli: &'c Client) -> Self::ExecuteOutput

define how a statement is executed with single time response

fn query(self, cli: &'c Client) -> Self::QueryOutput

define how a statement is queried with repeated response

impl<'s, P> Execute<&Client> for StatementPreparedQuery<'s, P>

where P: AsParams,

type ExecuteOutput = ResultFuture<RowAffected>

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

type QueryOutput = Ready<Result<GenericRowStream<&'s [Column], Typed>, Error>>

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

fn execute(self, cli: &Client) -> Self::ExecuteOutput

define how a statement is executed with single time response

fn query(self, cli: &Client) -> Self::QueryOutput

define how a statement is queried with repeated response

impl<'s, P> Execute<&Client> for StatementPreparedQueryOwned<'s, P>

where P: AsParams,

type ExecuteOutput = ResultFuture<RowAffected>

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

type QueryOutput = Ready<Result<GenericRowStream<Arc<[Column]>, Typed>, Error>>

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

fn execute(self, cli: &Client) -> Self::ExecuteOutput

define how a statement is executed with single time response

fn query(self, cli: &Client) -> Self::QueryOutput

define how a statement is queried with repeated response

impl<'c, P> Execute<&'c Client> for StatementQuery<'_, P>

where P: AsParams,

type ExecuteOutput = ResultFuture<RowAffected>

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

type QueryOutput = Ready<Result<RowStreamGuarded<'c, Client>, Error>>

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

fn execute(self, cli: &Client) -> Self::ExecuteOutput

define how a statement is executed with single time response

fn query(self, cli: &'c Client) -> Self::QueryOutput

define how a statement is queried with repeated response

impl<'c, P> Execute<&'c Client> for StatementSingleRTTQuery<'_, P>

where P: AsParams,

type ExecuteOutput = ResultFuture<RowAffected>

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

type QueryOutput = Ready<Result<RowStreamGuarded<'c, Client>, Error>>

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

fn execute(self, cli: &Client) -> Self::ExecuteOutput

define how a statement is executed with single time response

fn query(self, cli: &'c Client) -> Self::QueryOutput

define how a statement is queried with repeated response