Struct tokio_postgres::Client

source · 
pub struct Client { /* private fields */ }
Expand description

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.

Implementations§

source§

impl Client

source

pub async fn prepare(&self, query: &str) -> Result<Statement, 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.

source

pub async fn prepare_typed( &self, query: &str, parameter_types: &[Type], ) -> Result<Statement, Error>

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).

source

pub async fn query<T>( &self, statement: &T, params: &[&(dyn ToSql + Sync)], ) -> Result<Vec<Row>, Error>
where T: ?Sized + ToStatement,

Executes a statement, returning a vector 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.

The statement argument can either be a Statement, or a raw query string. If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with the prepare method.

source

pub async fn query_one<T>( &self, statement: &T, params: &[&(dyn ToSql + Sync)], ) -> Result<Row, Error>
where T: ?Sized + ToStatement,

Executes a statement which returns a single row, returning it.

Returns an error if the query does not return exactly one row.

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

The statement argument can either be a Statement, or a raw query string. If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with the prepare method.

source

pub async fn query_opt<T>( &self, statement: &T, params: &[&(dyn ToSql + Sync)], ) -> Result<Option<Row>, Error>
where T: ?Sized + ToStatement,

Executes a statements which returns zero or one rows, returning it.

Returns an error if the query returns more than one row.

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

The statement argument can either be a Statement, or a raw query string. If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with the prepare method.

source

pub async fn query_raw<T, P, I>( &self, statement: &T, params: I, ) -> Result<RowStream, Error>
where T: ?Sized + ToStatement, P: BorrowToSql, I: IntoIterator<Item = P>, I::IntoIter: ExactSizeIterator,

The maximally flexible version of query.

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

The statement argument can either be a Statement, or a raw query string. If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with the prepare method.

§Examples
use futures_util::{pin_mut, TryStreamExt};

let params: Vec<String> = vec![
    "first param".into(),
    "second param".into(),
];
let mut it = client.query_raw(
    "SELECT foo FROM bar WHERE biz = $1 AND baz = $2",
    params,
).await?;

pin_mut!(it);
while let Some(row) = it.try_next().await? {
    let foo: i32 = row.get("foo");
    println!("foo: {}", foo);
}
source

pub async fn query_typed( &self, query: &str, params: &[(&(dyn ToSql + Sync), Type)], ) -> Result<Vec<Row>, Error>

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

Compared to query, this method allows performing queries without three round trips (for prepare, execute, and close) by requiring the caller to specify parameter values along with their Postgres type. Thus, this is suitable in environments where prepared statements aren’t supported (such as Cloudflare Workers with Hyperdrive).

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

source

pub async fn query_typed_raw<P, I>( &self, query: &str, params: I, ) -> Result<RowStream, Error>
where P: BorrowToSql, I: IntoIterator<Item = (P, Type)>,

The maximally flexible version of query_typed.

Compared to query, this method allows performing queries without three round trips (for prepare, execute, and close) by requiring the caller to specify parameter values along with their Postgres type. Thus, this is suitable in environments where prepared statements aren’t supported (such as Cloudflare Workers with Hyperdrive).

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

§Examples
use futures_util::{pin_mut, TryStreamExt};
use tokio_postgres::types::Type;

let params: Vec<(String, Type)> = vec![
    ("first param".into(), Type::TEXT),
    ("second param".into(), Type::TEXT),
];
let mut it = client.query_typed_raw(
    "SELECT foo FROM bar WHERE biz = $1 AND baz = $2",
    params,
).await?;

pin_mut!(it);
while let Some(row) = it.try_next().await? {
    let foo: i32 = row.get("foo");
    println!("foo: {}", foo);
}
source

pub async fn execute<T>( &self, statement: &T, params: &[&(dyn ToSql + Sync)], ) -> Result<u64, Error>
where T: ?Sized + ToStatement,

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.

The statement argument can either be a Statement, or a raw query string. If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with the prepare method.

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

source

pub async fn execute_raw<T, P, I>( &self, statement: &T, params: I, ) -> Result<u64, Error>
where T: ?Sized + ToStatement, P: BorrowToSql, I: IntoIterator<Item = P>, I::IntoIter: ExactSizeIterator,

The maximally flexible version of execute.

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

The statement argument can either be a Statement, or a raw query string. If the same statement will be repeatedly executed (perhaps with different query parameters), consider preparing the statement up front with the prepare method.

source

pub async fn copy_in<T, U>(&self, statement: &T) -> Result<CopyInSink<U>, Error>
where T: ?Sized + ToStatement, U: Buf + 'static + 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 the Sink::close or finish methods. If it is not, the copy will be aborted.

source

pub async fn copy_out<T>(&self, statement: &T) -> Result<CopyOutStream, Error>
where T: ?Sized + ToStatement,

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

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

source

pub async fn simple_query( &self, query: &str, ) -> Result<Vec<SimpleQueryMessage>, Error>

Executes a sequence of SQL statements using the simple query protocol, returning the resulting 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!

source

pub async fn batch_execute(&self, query: &str) -> Result<(), Error>

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. This is intended for use when, for example, initializing a database schema.

§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!

source

pub async fn transaction(&mut self) -> Result<Transaction<'_>, Error>

Begins a new database transaction.

The transaction will roll back by default - use the commit method to commit it.

source

pub fn build_transaction(&mut self) -> TransactionBuilder<'_>

Returns a builder for a transaction with custom settings.

Unlike the transaction method, the builder can be used to control the transaction’s isolation level and other attributes.

source

pub fn cancel_token(&self) -> CancelToken

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

source

pub async fn cancel_query<T>(&self, tls: T) -> Result<(), Error>
where T: MakeTlsConnect<Socket>,

👎Deprecated since 0.6.0: use Client::cancel_token() instead

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).

source

pub async fn cancel_query_raw<S, T>( &self, stream: S, tls: T, ) -> Result<(), Error>
where S: AsyncRead + AsyncWrite + Unpin, T: TlsConnect<S>,

👎Deprecated since 0.6.0: use Client::cancel_token() instead

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

source

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.

source

pub fn is_closed(&self) -> bool

Determines if the connection to the server has already closed.

In that case, all future queries will fail.

Trait Implementations§

source§

impl Debug for Client

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl GenericClient for Client

source§

fn execute<'life0, 'life1, 'life2, 'life3, 'async_trait, T>( &'life0 self, query: &'life1 T, params: &'life2 [&'life3 (dyn ToSql + Sync)], ) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + Send + 'async_trait>>
where T: ?Sized + ToStatement + Sync + Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Like Client::execute.
source§

fn execute_raw<'life0, 'life1, 'async_trait, P, I, T>( &'life0 self, statement: &'life1 T, params: I, ) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + Send + 'async_trait>>
where T: ?Sized + ToStatement + Sync + Send + 'async_trait, P: BorrowToSql + 'async_trait, I: IntoIterator<Item = P> + Sync + Send + 'async_trait, I::IntoIter: ExactSizeIterator, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Like Client::execute_raw.
source§

fn query<'life0, 'life1, 'life2, 'life3, 'async_trait, T>( &'life0 self, query: &'life1 T, params: &'life2 [&'life3 (dyn ToSql + Sync)], ) -> Pin<Box<dyn Future<Output = Result<Vec<Row>, Error>> + Send + 'async_trait>>
where T: ?Sized + ToStatement + Sync + Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Like Client::query.
source§

fn query_one<'life0, 'life1, 'life2, 'life3, 'async_trait, T>( &'life0 self, statement: &'life1 T, params: &'life2 [&'life3 (dyn ToSql + Sync)], ) -> Pin<Box<dyn Future<Output = Result<Row, Error>> + Send + 'async_trait>>
where T: ?Sized + ToStatement + Sync + Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Like Client::query_one.
source§

fn query_opt<'life0, 'life1, 'life2, 'life3, 'async_trait, T>( &'life0 self, statement: &'life1 T, params: &'life2 [&'life3 (dyn ToSql + Sync)], ) -> Pin<Box<dyn Future<Output = Result<Option<Row>, Error>> + Send + 'async_trait>>
where T: ?Sized + ToStatement + Sync + Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Like Client::query_opt.
source§

fn query_raw<'life0, 'life1, 'async_trait, T, P, I>( &'life0 self, statement: &'life1 T, params: I, ) -> Pin<Box<dyn Future<Output = Result<RowStream, Error>> + Send + 'async_trait>>
where T: ?Sized + ToStatement + Sync + Send + 'async_trait, P: BorrowToSql + 'async_trait, I: IntoIterator<Item = P> + Sync + Send + 'async_trait, I::IntoIter: ExactSizeIterator, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Like Client::query_raw.
source§

fn query_typed<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, statement: &'life1 str, params: &'life2 [(&'life3 (dyn ToSql + Sync), Type)], ) -> Pin<Box<dyn Future<Output = Result<Vec<Row>, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Like Client::query_typed
source§

fn query_typed_raw<'life0, 'life1, 'async_trait, P, I>( &'life0 self, statement: &'life1 str, params: I, ) -> Pin<Box<dyn Future<Output = Result<RowStream, Error>> + Send + 'async_trait>>
where P: BorrowToSql + 'async_trait, I: IntoIterator<Item = (P, Type)> + Sync + Send + 'async_trait, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Like Client::query_typed_raw
source§

fn prepare<'life0, 'life1, 'async_trait>( &'life0 self, query: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Statement, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Like Client::prepare.
source§

fn prepare_typed<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, query: &'life1 str, parameter_types: &'life2 [Type], ) -> Pin<Box<dyn Future<Output = Result<Statement, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Like Client::prepare_typed.
source§

fn transaction<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<Transaction<'_>, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Like Client::transaction.
source§

fn batch_execute<'life0, 'life1, 'async_trait>( &'life0 self, query: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Like Client::batch_execute.
source§

fn simple_query<'life0, 'life1, 'async_trait>( &'life0 self, query: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<SimpleQueryMessage>, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Like Client::simple_query.
source§

fn client(&self) -> &Client

Returns a reference to the underlying Client.

Auto Trait Implementations§

§

impl Freeze for Client

§

impl !RefUnwindSafe for Client

§

impl Send for Client

§

impl Sync for Client

§

impl Unpin for Client

§

impl !UnwindSafe for Client

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V