Struct Transaction 

pub struct Transaction { /* private fields */ }

An open transaction. Owned, lifetime-free, and an Executor — any function written as fn f(db: &dyn Executor) accepts it, which is what lets model hooks run inside the caller’s transaction without knowing one exists.

commit and rollback consume self: using a finished transaction is a compile error, not a runtime one. Dropping without either abandons the connection — it is closed rather than returned to the pool, and the server rolls the transaction back. The lazy path is therefore always safe and merely expensive; commit is the only way to keep work. Prefer BeginExt::within, where neither a drop nor a forgotten commit can happen at all.

This crate itself issues the transaction vocabulary — BEGIN, COMMIT, ROLLBACK, SAVEPOINT n / RELEASE SAVEPOINT n / ROLLBACK TO SAVEPOINT n — which is identical across PostgreSQL, MySQL and SQLite, so no backend re-implements (or drifts on) transaction semantics. Where the engines stop agreeing — isolation levels, access modes — the vocabulary is still written here, once, but per family and with the disagreements spelled out: see TxOptions and BeginWith.

Implementations

impl Transaction

pub async fn begin_on(conn: Box<dyn RawConnection>) -> Result<Self, ExecError>

Open a transaction on an exclusively-owned connection. Backend-facing: a backend’s Begin impl checks a connection out and hands it here.

pub async fn begin_on_with( conn: Box<dyn RawConnection>, opts: TxOptions, ) -> Result<Self, ExecError>

Open a transaction with explicit TxOptions. Backend-facing, the counterpart of BeginWith::begin_with.

The options are turned into statements by TxOptions::plan before anything is sent, so an option this engine cannot honour is refused with the connection untouched — it goes back to its pool clean rather than being abandoned. Every statement of the plan runs on this one connection, ahead of any statement the caller issues; if one of them fails the connection is abandoned rather than returned, because a half-applied plan (MySQL’s SET TRANSACTION having landed without its START TRANSACTION) would otherwise leak into whatever transaction this pooled connection served next.

pub fn options(&self) -> TxOptions

The options this transaction was opened with — TxOptions::new’s defaults for one begun by Begin::begin.

pub async fn commit(self) -> Result<(), ExecError>

Commit. Consumes the transaction; on success the connection goes back to wherever it came from.

pub async fn rollback(self) -> Result<(), ExecError>

Roll back explicitly. Consumes the transaction; cheaper than dropping, because the connection is returned cleanly instead of closed.

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

where F: AsyncFnOnce(&Transaction) -> Result<T, E>, E: From<ExecError>,

A nested transaction, via SAVEPOINT.

The savepoint has no handle to leak: Ok(_) releases it, Err(_) rolls back to it, and the outer transaction lives on either way. The closure receives this same transaction, so every &dyn Executor-taking helper works unchanged inside. Nesting is unbounded; depth-numbered names never collide.

Trait Implementations

impl Atomic for Transaction

Inside a transaction: atomic is Transaction::savepoint.

Not an overlapping impl, and not by luck: Transaction does not implement Begin, which is the design decision above holding the two impls apart.

fn atomic<T, E, F>(&self, f: F) -> impl Future<Output = Result<T, E>>

where F: AsyncFnOnce(&Transaction) -> Result<T, E>, E: From<ExecError>,

Run f as one all-or-nothing block, nesting if the receiver is already a transaction.

impl Atomic for &Transaction

A reference to a transaction — what makes the bare impl Atomic parameter form work, since that is the type a scope closure hands you.

Executor is implemented for &E and Arc<E> for the same reason: a caller should not have to know whether what it holds is the value or a handle to it. Coherent with the blanket impl for the same reason Transaction’s own impl is — &Transaction is not Begin either.

fn atomic<T, E, F>(&self, f: F) -> impl Future<Output = Result<T, E>>

where F: AsyncFnOnce(&Transaction) -> Result<T, E>, E: From<ExecError>,

Run f as one all-or-nothing block, nesting if the receiver is already a transaction.

impl Debug for Transaction

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Transaction

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Executor for Transaction

fn family(&self) -> Family

Which engine family this executor talks to.

fn fetch(&self, stmt: Statement) -> ExecFuture<'_, Result<Vec<Row>, ExecError>>

Run a statement and collect every row — SELECT, or any mutation with RETURNING.

fn execute( &self, stmt: Statement, ) -> ExecFuture<'_, Result<ExecResult, ExecError>>

Run a statement for its side effect.