Struct Transaction 

pub struct Transaction<'p, DB> { /* private fields */ }

Transaction builder for composing multi-entity operations.

Use Transaction::new to create a builder, chain .with_*() methods to declare which entities you’ll use, then call .run() to execute.

Type Parameters

• 'p — Pool lifetime
• DB — Database pool type (e.g., PgPool)

Example

Transaction::new(&pool)
    .run(async |ctx| {
        let user = ctx.users().find_by_id(id).await?;
        ctx.orders().create(order).await?;
        Ok(())
    })
    .await?;

Implementations

impl<'p, DB> Transaction<'p, DB>

pub const fn new(pool: &'p DB) -> Self

Create a new transaction builder.

Arguments

• pool — Database connection pool

Example

let tx = Transaction::new(&pool);

pub const fn pool(&self) -> &'p DB

Get reference to the underlying pool.

impl Transaction<'_, PgPool>

pub async fn run<F, T, E>(self, f: F) -> Result<T, E>

where F: AsyncFnOnce(&mut TransactionContext) -> Result<T, E>, E: From<Error> + Debug,

Execute a closure within a PostgreSQL transaction.

Commits the transaction explicitly when the closure returns Ok. On Err, the transaction context is dropped and sqlx rolls back automatically via its Drop implementation.

The closure receives &mut TransactionContext (not by value) so that run retains ownership and can invoke commit().await on success.

Type Parameters

• F — Async closure
• T — Success type
• E — Error type (must be convertible from sqlx::Error)

Example

Transaction::new(&pool)
    .run(async |ctx| {
        let user = ctx.users().create(dto).await?;
        Ok(user)
    })
    .await?;

Errors

Propagates any error from the closure, from begin, or from commit.

pub async fn run_with_commit<F, Fut, T, E>(self, f: F) -> Result<T, E>

where F: FnOnce(TransactionContext) -> Fut + Send, Fut: Future<Output = Result<T, E>> + Send, E: From<Error> + Debug,

Execute a closure within a transaction with explicit commit.

⚠️ The closure MUST call ctx.commit().await on every successful path

run_with_commit hands ownership of TransactionContext to the closure. There is no type-level guarantee that the closure commits; if it returns Ok(...) without calling commit, ctx is dropped and the underlying sqlx::Transaction::Drop silently rolls back. The caller observes Ok and assumes the writes persisted — they did not. This is the same failure mode that affected the old run() implementation; here it is preserved on purpose so callers can implement conditional commit logic, at the cost of moving the responsibility onto the closure.

Prefer run unless you genuinely need to decide commit-or-rollback inside the closure. run performs the commit automatically on Ok and rolls back on Err, eliminating this footgun.

Examples

Correct — closure commits on the success path:

Transaction::new(&pool)
    .run_with_commit(|mut ctx| async move {
        let user = ctx.users().create(dto).await?;
        ctx.commit().await?;     // <-- required
        Ok(user)
    })
    .await?;

Wrong — closure returns Ok without committing; the write is rolled back when ctx drops, but the caller sees Ok(user):

Transaction::new(&pool)
    .run_with_commit(|mut ctx| async move {
        let user = ctx.users().create(dto).await?;
        // BUG: forgot `ctx.commit().await?` — the row is rolled back.
        Ok(user)
    })
    .await?;

Conditional commit — the intended use case:

Transaction::new(&pool)
    .run_with_commit(|mut ctx| async move {
        let user = ctx.users().create(dto).await?;
        if user.flagged {
            ctx.rollback().await?;
            return Ok(None);
        }
        ctx.commit().await?;
        Ok(Some(user))
    })
    .await?;

Errors

Propagates any error from the closure or database transaction.