Trait TxnSession 

pub trait TxnSession: Send {
    // Required methods
    fn commit(&mut self, all: bool) -> EngineResult;
    fn rollback(&mut self, all: bool) -> EngineResult;

    // Provided methods
    fn write_row(&mut self, table: &str, row: &[u8]) -> EngineResult { ... }
    fn update_row(
        &mut self,
        table: &str,
        old: &[u8],
        new: &[u8],
    ) -> EngineResult { ... }
    fn delete_row(&mut self, table: &str, row: &[u8]) -> EngineResult { ... }
    fn prepare(&mut self, all: bool) -> EngineResult { ... }
    fn savepoint_set(&mut self, sv: &mut [u8]) -> EngineResult { ... }
    fn savepoint_rollback(&mut self, sv: &[u8]) -> EngineResult { ... }
    fn savepoint_release(&mut self, sv: &[u8]) -> EngineResult { ... }
    fn savepoint_rollback_can_release_mdl(&self) -> bool { ... }
}

The transaction state for one connection.

A transactional Handlerton creates one of these per connection (via Handlerton::begin_transaction). MySQL stores it in the connection’s ha_data slot and drives it through commit / rollback, so a TxnSession outlives the per-table handler and accumulates work across every statement of the transaction.

The Send bound is required because a connection may be served by different threads over its lifetime, so the session moves across threads — do not relax it.

all distinguishes the two boundaries MySQL signals on the same callback: true is a real transaction commit/rollback (the connection is in autocommit, or COMMIT / ROLLBACK ran); false is the end of a single statement within a larger transaction.

Required Methods

fn commit(&mut self, all: bool) -> EngineResult

Commit the work accumulated so far.

Errors

Returns an EngineError if the commit fails; MySQL surfaces it to the client and the statement / transaction is reported as failed.

fn rollback(&mut self, all: bool) -> EngineResult

Discard the work accumulated so far.

Errors

Returns an EngineError if the rollback fails; this is reported to MySQL but the transaction is still considered rolled back.

Provided Methods

fn write_row(&mut self, table: &str, row: &[u8]) -> EngineResult

Stage a row written into table as part of this transaction.

A transactional engine receives each row write here (rather than on the per-table handler) so the change is buffered until commit makes it visible or rollback discards it. row is the MySQL row image (record[0]). The default ignores the write; an engine that stores data overrides this to buffer it.

Errors

Returns an EngineError if the row cannot be staged (e.g. out of memory).

fn update_row(&mut self, table: &str, old: &[u8], new: &[u8]) -> EngineResult

Stage a row update. old is the pre-image (for rollback / pre-image-keyed map lookups) and new is the post-image. Same buffering contract as Self::write_row; default is a no-op.

Errors

Returns an EngineError if the update cannot be staged.

fn delete_row(&mut self, table: &str, row: &[u8]) -> EngineResult

Stage a row deletion. row is the pre-image of the row about to be removed. Same buffering contract as Self::write_row; default is a no-op.

Errors

Returns an EngineError if the delete cannot be staged.

fn prepare(&mut self, all: bool) -> EngineResult

Prepare phase: flush the transaction so a following commit is durable.

MySQL drives this whenever the engine takes part in two-phase commit — most importantly alongside the binary log, which is on by default — so a transactional engine must handle it. The default reports success, which is correct for an engine with nothing durable to prepare; override it to flush real state.

Errors

Returns an EngineError if the engine cannot prepare; MySQL then rolls the transaction back.

fn savepoint_set(&mut self, sv: &mut [u8]) -> EngineResult

Establish a savepoint at the transaction’s current point. sv is the engine’s per-savepoint scratch (savepoint_offset bytes, declared by Handlerton::savepoint_offset): write whatever the engine needs to identify this savepoint on rollback. sv is only byte-aligned, so write it through copy_from_slice / to_le_bytes rather than a typed pointer store. Defaults to no-op success.

Errors

Returns an EngineError if the savepoint cannot be recorded.

fn savepoint_rollback(&mut self, sv: &[u8]) -> EngineResult

Roll the transaction back to the savepoint whose scratch is sv (as written by savepoint_set), discarding work done since. Defaults to no-op success.

Errors

Returns an EngineError if the rollback to savepoint fails.

fn savepoint_release(&mut self, sv: &[u8]) -> EngineResult

Release (forget) the savepoint whose scratch is sv, keeping its work part of the transaction. Defaults to no-op success.

Errors

Returns an EngineError if the release fails.

fn savepoint_rollback_can_release_mdl(&self) -> bool

Whether it is safe to release metadata locks acquired after a savepoint when rolling back to it. Defaults to true (the engine holds no locks that a savepoint rollback must preserve).

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors