Struct AsyncPgConnection

pub struct AsyncPgConnection { /* private fields */ }

A connection to a PostgreSQL database.

Connection URLs should be in the form postgres://[user[:password]@]host/database_name

Checkout the documentation of the tokio_postgres crate for details about the format

Pipelining

This connection supports pipelined requests. Pipelining can improve performance in use cases in which multiple, independent queries need to be executed. In a traditional workflow, each query is sent to the server after the previous query completes. In contrast, pipelining allows the client to send all of the queries to the server up front, minimizing time spent by one side waiting for the other to finish sending data:

            Sequential                              Pipelined
| Client         | Server          |    | Client         | Server          |
|----------------|-----------------|    |----------------|-----------------|
| send query 1   |                 |    | send query 1   |                 |
|                | process query 1 |    | send query 2   | process query 1 |
| receive rows 1 |                 |    | send query 3   | process query 2 |
| send query 2   |                 |    | receive rows 1 | process query 3 |
|                | process query 2 |    | receive rows 2 |                 |
| receive rows 2 |                 |    | receive rows 3 |                 |
| send query 3   |                 |
|                | process query 3 |
| receive rows 3 |                 |

In both cases, the PostgreSQL server is executing the queries sequentially - pipelining just allows both sides of the connection to work concurrently when possible.

Pipelining happens automatically when futures are polled concurrently (for example, by using the futures join combinator):

use diesel_async::RunQueryDsl;

      let q1 = diesel::select(1_i32.into_sql::<Integer>());
      let q2 = diesel::select(2_i32.into_sql::<Integer>());

      // construct multiple futures for different queries
      let f1 = q1.get_result::<i32>(conn);
      let f2 = q2.get_result::<i32>(conn);

      // wait on both results
      let res = futures_util::try_join!(f1, f2)?;

      assert_eq!(res.0, 1);
      assert_eq!(res.1, 2);

TLS

Connections created by AsyncPgConnection::establish do not support TLS.

TLS support for tokio_postgres connections is implemented by external crates, e.g. tokio_postgres_rustls.

AsyncPgConnection::try_from_client_and_connection can be used to construct a connection from an existing tokio_postgres::Connection with TLS enabled.

Implementations

impl AsyncPgConnection

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

Build a transaction, specifying additional details such as isolation level

See TransactionBuilder for more examples.

conn.build_transaction()
    .read_only()
    .serializable()
    .deferrable()
    .run(|conn| async move { Ok(()) }.scope_boxed())
    .await

pub async fn try_from( conn: Client, ) -> Result<AsyncPgConnection, ConnectionError>

Construct a new AsyncPgConnection instance from an existing tokio_postgres::Client

pub async fn try_from_client_and_connection<S>( client: Client, conn: Connection<Socket, S>, ) -> Result<AsyncPgConnection, ConnectionError>

where S: TlsStream + Unpin + Send + 'static,

Constructs a new AsyncPgConnection from an existing tokio_postgres::Client and tokio_postgres::Connection

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.

Trait Implementations

impl AsyncConnection for AsyncPgConnection

type LoadFuture<'conn, 'query> = Pin<Box<dyn Future<Output = Result<<AsyncPgConnection as AsyncConnection>::Stream<'conn, 'query>, Error>> + Send + 'query>>

The future returned by AsyncConnection::load

type ExecuteFuture<'conn, 'query> = Pin<Box<dyn Future<Output = Result<usize, Error>> + Send + 'query>>

The future returned by AsyncConnection::execute

type Stream<'conn, 'query> = Pin<Box<dyn Stream<Item = Result<PgRow, Error>> + Send>>

The inner stream returned by AsyncConnection::load

type Row<'conn, 'query> = PgRow

The row type used by the stream returned by AsyncConnection::load

type Backend = Pg

The backend this type connects to

fn establish<'life0, 'async_trait>( database_url: &'life0 str, ) -> Pin<Box<dyn Future<Output = Result<AsyncPgConnection, ConnectionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, AsyncPgConnection: 'async_trait,

Establishes a new connection to the database

fn set_instrumentation(&mut self, instrumentation: impl Instrumentation)

Set a specific Instrumentation implementation for this connection

fn transaction<'a, 'life0, 'async_trait, R, E, F>( &'life0 mut self, callback: F, ) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'async_trait>>

where 'a: 'async_trait, 'life0: 'async_trait, F: for<'r> FnOnce(&'r mut Self) -> Pin<Box<dyn ScopedFuture<'a, 'r, PhantomData<&'r &'a ()>, Output = Result<R, E>> + Send + 'r>> + Send + 'a + 'async_trait, E: From<Error> + Send + 'a + 'async_trait, R: Send + 'a + 'async_trait, Self: 'async_trait,

Executes the given function inside of a database transaction

fn begin_test_transaction<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Creates a transaction that will never be committed. This is useful for tests. Panics if called while inside of a transaction or if called with a connection containing a broken transaction

fn test_transaction<'a, 'async_trait, R, E, F>( &'a mut self, f: F, ) -> Pin<Box<dyn Future<Output = R> + Send + 'async_trait>>

where 'a: 'async_trait, F: for<'r> FnOnce(&'r mut Self) -> Pin<Box<dyn ScopedFuture<'a, 'r, PhantomData<&'r &'a ()>, Output = Result<R, E>> + Send + 'r>> + Send + 'a + 'async_trait, E: Debug + Send + 'a + 'async_trait, R: Send + 'a + 'async_trait, Self: 'a + 'async_trait,

Executes the given function inside a transaction, but does not commit it. Panics if the given function returns an error.

impl Drop for AsyncPgConnection

fn drop(&mut self)

Executes the destructor for this type.

impl SimpleAsyncConnection for AsyncPgConnection

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

where 'life0: 'async_trait, 'life1: 'async_trait, AsyncPgConnection: 'async_trait,

Execute multiple SQL statements within the same string.

impl<'b, Changes, Output, Tab, V> UpdateAndFetchResults<Changes, Output> for AsyncPgConnection

where Output: Send, Changes: Copy + AsChangeset<Target = Tab> + Send + Identifiable<Table = Tab>, Tab: Table + FindDsl<<Changes as Identifiable>::Id> + 'b, <Tab as FindDsl<<Changes as Identifiable>::Id>>::Output: IntoUpdateTarget<Table = Tab, WhereClause = V>, UpdateStatement<Tab, V, <Changes as AsChangeset>::Changeset>: AsQuery, UpdateStatement<<Changes as HasTable>::Table, <Changes as IntoUpdateTarget>::WhereClause, <Changes as AsChangeset>::Changeset>: LoadQuery<'b, AsyncPgConnection, Output>, V: Send + 'b, <Changes as AsChangeset>::Changeset: Send + 'b, <Tab as QuerySource>::FromClause: Send,

fn update_and_fetch<'life0, 'async_trait>( &'life0 mut self, changeset: Changes, ) -> Pin<Box<dyn Future<Output = Result<Output, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, Changes: 'async_trait, <Changes as AsChangeset>::Changeset: 'async_trait, AsyncPgConnection: 'async_trait,

See the traits documentation.