Struct diesel_async::AsyncPgConnection

pub struct AsyncPgConnection { /* private fields */ }

Available on crate feature postgres only.

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

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

      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::try_join!(f1, f2)?;

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

Implementations

impl AsyncPgConnection

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

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(()) }.boxed())
    .await

pub async fn try_from(conn: Client) -> ConnectionResult<Self>

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

Trait Implementations

impl AsyncConnection for AsyncPgConnection

type Backend = Pg

The backend this type connects to

fn establish<'life0, 'async_trait>(
    database_url: &'life0 str
) -> Pin<Box<dyn Future<Output = ConnectionResult<Self>> + Send + 'async_trait>>where
    'life0: 'async_trait,
    Self: 'async_trait,

Establishes a new connection to the database

fn transaction<'life0, 'async_trait, R, E, F>(
    &'life0 mut self,
    callback: F
) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'async_trait>>where
    F: FnOnce(&mut Self) -> BoxFuture<'_, Result<R, E>> + Send,
    E: From<Error> + Send,
    R: Send,
    R: 'async_trait,
    E: 'async_trait,
    F: 'async_trait,
    'life0: '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 = QueryResult<()>> + 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

impl<'conn, 'query> AsyncConnectionGatWorkaround<'conn, 'query, Pg> for AsyncPgConnection

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

The future returned by AsyncConnection::load

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

The future returned by AsyncConnection::execute

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

The inner stream returned by AsyncConnection::load

type Row = PgRow

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

impl SimpleAsyncConnection for AsyncPgConnection

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

Execute multiple SQL statements within the same string.

impl<'b, Changes, Output> UpdateAndFetchResults<Changes, Output> for AsyncPgConnectionwhere
    Output: Send,
    Changes: Copy + AsChangeset<Target = <Changes as HasTable>::Table> + IntoUpdateTarget + Send,
    Update<Changes, Changes>: LoadQuery<'b, AsyncPgConnection, Output>,
    Changes::Table: Send + 'b,
    Changes::WhereClause: Send + 'b,
    Changes::Changeset: Send + 'b,
    <Changes::Table as Table>::AllColumns: ValidGrouping<()>,
    <<Changes::Table as Table>::AllColumns as ValidGrouping<()>>::IsAggregate: MixedAggregates<No, Output = No>,
    <Changes::Table as QuerySource>::FromClause: Send,

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

See the traits documentation.