Struct diesel_async::AsyncPgConnection

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

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§

source§

impl AsyncPgConnection

source

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

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

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

source

pub async fn try_from_client_and_connection<S>( client: Client, conn: Connection<Socket, S>, ) -> ConnectionResult<Self>
where S: TlsStream + Unpin + Send + 'static,

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

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.

Trait Implementations§

source§

impl AsyncConnection for AsyncPgConnection

source§

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

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

The future returned by AsyncConnection::execute
source§

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

The inner stream returned by AsyncConnection::load
source§

type Row<'conn, 'query> = PgRow

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

type Backend = Pg

The backend this type connects to
source§

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

Establishes a new connection to the database Read more
source§

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

Set a specific Instrumentation implementation for this connection
source§

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 F: for<'r> FnOnce(&'r mut Self) -> ScopedBoxFuture<'a, 'r, Result<R, E>> + Send + 'a + 'async_trait, E: From<Error> + Send + 'a + 'async_trait, R: Send + 'a + 'async_trait, Self: 'async_trait, 'a: 'async_trait, 'life0: 'async_trait,

Executes the given function inside of a database transaction Read more
source§

fn begin_test_transaction<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = QueryResult<()>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: '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
source§

fn test_transaction<'a, 'async_trait, R, E, F>( &'a mut self, f: F, ) -> Pin<Box<dyn Future<Output = R> + Send + 'async_trait>>
where F: for<'r> FnOnce(&'r mut Self) -> ScopedBoxFuture<'a, 'r, Result<R, E>> + Send + 'a + 'async_trait, E: Debug + Send + 'a + 'async_trait, R: Send + 'a + 'async_trait, Self: 'a + 'async_trait, 'a: 'async_trait,

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

impl Drop for AsyncPgConnection

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl SimpleAsyncConnection for AsyncPgConnection

source§

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

Execute multiple SQL statements within the same string. Read more
source§

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::Id> + 'b, Find<Tab, Changes::Id>: IntoUpdateTarget<Table = Tab, WhereClause = V>, UpdateStatement<Tab, V, Changes::Changeset>: AsQuery, Update<Changes, Changes>: LoadQuery<'b, Self, Output>, V: Send + 'b, Changes::Changeset: Send + 'b, Tab::FromClause: Send,

source§

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, Changes::Changeset: 'async_trait, Self: 'async_trait, 'life0: 'async_trait,

See the traits documentation.

Auto Trait Implementations§

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> IntoSql for T

source§

fn into_sql<T>(self) -> Self::Expression

Convert self to an expression for Diesel’s query builder. Read more
source§

fn as_sql<'a, T>(&'a self) -> <&'a Self as AsExpression<T>>::Expression
where &'a Self: AsExpression<T>, T: SqlType + TypedExpressionType,

Convert &self to an expression for Diesel’s query builder. Read more
source§

impl<T, Conn> RunQueryDsl<Conn> for T

source§

fn execute<'conn, 'query>( self, conn: &'conn mut Conn, ) -> Conn::ExecuteFuture<'conn, 'query>
where Conn: AsyncConnection + Send, Self: ExecuteDsl<Conn> + 'query,

Executes the given command, returning the number of rows affected. Read more
source§

fn load<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> LoadFuture<'conn, 'query, Self, Conn, U>
where U: Send, Conn: AsyncConnection, Self: LoadQuery<'query, Conn, U> + 'query,

Executes the given query, returning a Vec with the returned rows. Read more
source§

fn load_stream<'conn, 'query, U>( self, conn: &'conn mut Conn, ) -> Self::LoadFuture<'conn>
where Conn: AsyncConnection, U: 'conn, Self: LoadQuery<'query, Conn, U> + 'query,

Executes the given query, returning a Stream with the returned rows. Read more
source§

fn get_result<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> GetResult<'conn, 'query, Self, Conn, U>
where U: Send + 'conn, Conn: AsyncConnection, Self: LoadQuery<'query, Conn, U> + 'query,

Runs the command, and returns the affected row. Read more
source§

fn get_results<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> LoadFuture<'conn, 'query, Self, Conn, U>
where U: Send, Conn: AsyncConnection, Self: LoadQuery<'query, Conn, U> + 'query,

Runs the command, returning an Vec with the affected rows. Read more
source§

fn first<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> GetResult<'conn, 'query, Limit<Self>, Conn, U>
where U: Send + 'conn, Conn: AsyncConnection, Self: LimitDsl, Limit<Self>: LoadQuery<'query, Conn, U> + Send + 'query,

Attempts to load a single record. Read more
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