diesel-async Documentation

Diesel-async supports several connection pooling crates via the AsyncDieselConnectionManager.

Deadpool

Requires the deadpool feature. Use Pool::builder(config).build()?.

BB8

Requires the bb8 feature. Use Pool::builder().build(config).await?.

Mobc

Requires the mobc feature. Use Pool::new(config).

// Deadpool example
use diesel_async::pooled_connection::AsyncDieselConnectionManager;
use diesel_async::pooled_connection::deadpool::Pool;
use diesel_async::RunQueryDsl;

let config = AsyncDieselConnectionManager::<diesel_async::AsyncPgConnection>::new(std::env::var("DATABASE_URL")?);
let pool = Pool::builder(config).build()?;
let mut conn = pool.get().await?;
let res = users::table.select(User::as_select()).load::(&mut conn).await?;

To use diesel-async, you must include both diesel and diesel-async in your Cargo.toml. diesel-async acts as an async drop-in replacement for database interaction, while diesel provides the query builder and model definitions. You do not need to enable backend features in the base diesel crate; instead, enable the specific database feature in diesel-async (e.g., postgres, mysql, or sqlite).

[dependencies]
diesel = "2.3.0" # no backend features need to be enabled
diesel-async = { version = "0.7.0", features = ["postgres"] }

Transaction management is handled by a TransactionManager associated with an AsyncConnection.

When using high-level transaction APIs (like AsyncConnection::transaction), the manager follows this lifecycle:

1. Begin: Calls begin_transaction. If the current transaction depth is > 0, it creates a SAVEPOINT instead of a BEGIN.
2. Execute: Runs the provided async closure.
3. Commit/Rollback:
   • If the closure returns Ok, it calls commit_transaction. If depth > 1, this releases the savepoint.
   • If the closure returns Err, it calls rollback_transaction. If depth > 1, it rolls back to the most recent savepoint.

This nesting mechanism allows for safe, composable transactions and savepoints.

diesel-async is an extension to the main diesel crate. It provides async variants of core Diesel traits that perform actual I/O work. To use it, you typically replace synchronous Diesel trait method calls and connection types with their diesel-async counterparts.

Key trait mappings:

• diesel::prelude::RunQueryDsl $\rightarrow$ diesel_async::RunQueryDsl
• diesel::connection::Connection $\rightarrow$ diesel_async::AsyncConnection
• diesel::query_dsl::UpdateAndFetchResults $\rightarrow$ diesel_async::UpdateAndFetchResults

use diesel::prelude::*;
use diesel_async::{RunQueryDsl, AsyncConnection};

// Use ordinary diesel query DSL, but execute via async RunQueryDsl
let data = users
    .filter(id.gt(0))
    .load::<(i32, String)>(&mut connection)
    .await?;

A connection is considered 'broken' if it is in an unreliable state, which is critical for connection pool implementations to know so they can discard the connection rather than reusing it.

A connection is considered broken if:

1. The TransactionManager is in an error state (TransactionManagerStatus::Error).
2. The connection has an open transaction that was not started as a test_transaction (e.g., a transaction was left uncommitted/unrolled due to a future being dropped).
3. A critical transaction operation (like BEGIN, COMMIT, or ROLLBACK) was interrupted or canceled mid-execution (tracked via the is_broken atomic flag in AnsiTransactionManager).

When using diesel_async with PostgreSQL, you can use AsyncPgConnection::build_transaction() to obtain a TransactionBuilder. This builder allows you to specify the isolation level, read mode, and deferrability of the transaction before executing it.

Important: The builder does nothing until you call .run() with an async closure. If the closure returns an error, the transaction is automatically rolled back. If it returns Ok, the transaction is committed.

// Example: Setting up a read-only, serializable transaction
conn.build_transaction()
    .serializable()
    .read_only()
    .run(async |conn| {
        // Your database operations here
        Ok(())
    })
    .await?;

To connect to a MySQL database asynchronously, use AsyncMysqlConnection::establish. Connection URLs must follow the format: mysql://[user[:password]@]host/database_name.

Upon establishment, the connection automatically executes setup queries to set the time zone to UTC and configure the character set to utf8mb4 for client, connection, and results.

use diesel_async::AsyncMysqlConnection;

let mut conn = AsyncMysqlConnection::establish("mysql://user:pass@localhost/db_name").await?;

Instead of loading all results into a collection (like a Vec), you can use .load_stream() from the RunQueryDsl trait to return a Stream of QueryResult<T>. This allows you to process database rows one by one as they are received.

// use ordinary diesel query dsl to construct your query
let data: impl Stream<Item = QueryResult<User>> = users::table
    .filter(users::id.gt(0))
    .or_filter(users::name.like("%Luke"))
    .select(User::as_select())
    // execute the query via the provided
    // async `diesel_async::RunQueryDsl`
    .load_stream(&mut connection)
    .await?;

Wrap multiple database statements in a transaction using connection.transaction. The transaction automatically rolls back if the inner closure returns an error. Because the closure is async, you must use .scope_boxed() to handle the lifetime of the async block within the transaction.

connection.transaction::<_, diesel::result::Error, _>(|conn| async move {
         diesel::insert_into(users::table)
             .values(users::name.eq("Ruby"))
             .execute(conn)
             .await?;

         let all_names = users::table.select(users::name).load::<String>(conn).await?;
         Ok(())
       }.scope_boxed()
    ).await?;

The following feature flags control available connection types and functionality: