Struct tokio_postgres::Client

pub struct Client(_);

An asynchronous PostgreSQL client.

The client is one half of what is returned when a connection is established. Users interact with the database through this client object.

Methods

impl Client

pub fn prepare(&mut self, query: &str) -> Prepare

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 prepare_typed(&mut self, query: &str, param_types: &[Type]) -> Prepare

Like prepare, but allows the types of query parameters to be explicitly specified.

The list of types may be smaller than the number of parameters - the types of the remaining parameters will be inferred. For example, client.prepare_typed(query, &[]) is equivalent to client.prepare(query).

pub fn execute(
    &mut self,
    statement: &Statement,
    params: &[&dyn ToSql]
) -> Execute

Executes a statement, returning the number of rows modified.

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

Panics

Panics if the number of parameters provided does not match the number expected.

pub fn query(&mut self, statement: &Statement, params: &[&dyn ToSql]) -> Query

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

Panics

Panics if the number of parameters provided does not match the number expected.

pub fn bind(&mut self, statement: &Statement, params: &[&dyn ToSql]) -> Bind

Binds a statement to a set of parameters, creating a Portal which can be incrementally queried.

Portals only last for the duration of the transaction in which they are created - in particular, a portal created outside of a transaction is immediately destroyed. Portals can only be used on the connection that created them.

Panics

Panics if the number of parameters provided does not match the number expected.

pub fn query_portal(&mut self, portal: &Portal, max_rows: i32) -> QueryPortal

Continues execution of a portal, returning a stream of the resulting rows.

Unlike query, portals can be incrementally evaluated by limiting the number of rows returned in each call to query_portal. If the requested number is negative or 0, all rows will be returned.

pub fn copy_in<S>(
    &mut self,
    statement: &Statement,
    params: &[&dyn ToSql],
    stream: S
) -> CopyIn<S> where
    S: Stream,
    S::Item: IntoBuf,
    <S::Item as IntoBuf>::Buf: Send,
    S::Error: Into<Box<dyn StdError + Sync + Send>>, 

Executes a COPY FROM STDIN statement, returning the number of rows created.

The data in the provided stream is passed along to the server verbatim; it is the caller's responsibility to ensure it uses the proper format.

pub fn copy_out(
    &mut self,
    statement: &Statement,
    params: &[&dyn ToSql]
) -> CopyOut

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

pub fn simple_query(&mut self, query: &str) -> SimpleQuery

Executes a sequence of SQL statements using the simple query protocol.

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 stream over the rows, this method returns a stream over 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 imbed that data in the request. Do not form statements via string concatenation and pass them to this method!

pub fn build_transaction(&mut self) -> TransactionBuilder

A utility method to wrap a future in a database transaction.

The returned future will start a transaction and then run the provided future. If the future returns Ok, it will commit the transaction, and if it returns Err, it will roll the transaction back.

This is simply a convenience API; it's roughly equivalent to:

client.batch_execute("BEGIN")
    .and_then(your_future)
    .and_then(client.batch_execute("COMMIT"))
    .or_else(|e| client.batch_execute("ROLLBACK").then(|_| Err(e)))

Warning

Unlike the other futures created by a client, this future is not atomic with respect to other requests. If you attempt to execute it concurrently with other futures created by the same connection, they will interleave!

pub fn cancel_query<T>(&mut self, make_tls_mode: T) -> CancelQuery<T> where
    T: MakeTlsConnect<Socket>, 

Attempts to cancel an in-progress query.

The server provides no information about whether a cancellation attempt was successful or not. An error will only be returned if the client was unable to connect to the database.

Requires the runtime Cargo feature (enabled by default).

pub fn cancel_query_raw<S, T>(
    &mut self,
    stream: S,
    tls_mode: T
) -> CancelQueryRaw<S, T> where
    S: AsyncRead + AsyncWrite,
    T: TlsConnect<S>, 

Like cancel_query, but uses a stream which is already connected to the server rather than opening a new connection itself.

pub fn is_closed(&self) -> bool

Determines if the connection to the server has already closed.

In that case, all future queries will fail.

pub fn poll_idle(&mut self) -> Poll<(), Error>

Polls the client to check if it is idle.

A connection is idle if there are no outstanding requests, whether they have begun being polled or not. For example, this can be used by a connection pool to ensure that all work done by one checkout is done before making the client available for a new request. Otherwise, any non-completed work from the first request could interleave with the second.