Struct Transaction 

pub struct Transaction { /* private fields */ }

事务对象，封装一个数据库事务

内部连接以 Option<Box<dyn Connection>> 形式持有：

• 事务执行期间，连接存在
• 调用 take_connection() 可在 commit/rollback 后取回连接归还到连接池
• Drop 时若事务仍 Active，会尝试 spawn 后台 rollback 任务

Implementations

impl Transaction

pub fn new(conn: Box<dyn Connection>, options: TransactOptions) -> Transaction

创建新事务（调用方应先通过 connection.begin_transaction() 启动事务）

L-5 修复：补充示例文档

通常通过 Connection::begin_transaction() 创建，而不是直接调用此方法。

示例

use sz_orm_pool::transaction::{Transaction, TransactOptions};

// 通常通过 Connection::begin_transaction 创建
let tx = Transaction::new(conn, TransactOptions::default());
assert!(tx.is_active());

pub fn state(&self) -> TransactionState

获取当前事务状态

pub fn is_active(&self) -> bool

检查事务是否仍然活跃

pub async fn commit(&mut self) -> Result<(), TxError>

提交事务

L-5 修复：补充示例文档

提交后事务状态变为 Committed，不可再次 commit/rollback。 若未提交就 drop，会自动 rollback。

示例

tx.execute("INSERT INTO users (name) VALUES ('Alice')").await?;
tx.execute("INSERT INTO users (name) VALUES ('Bob')").await?;
tx.commit().await?; // 提交两条 INSERT

pub async fn rollback(&mut self) -> Result<(), TxError>

回滚事务

pub async fn execute(&mut self, sql: &str) -> Result<u64, TxError>

在事务中执行 SQL（在事务未结束时执行）

pub async fn query( &mut self, sql: &str, ) -> Result<Vec<HashMap<String, Value>>, TxError>

在事务中执行查询

pub async fn savepoint(&mut self) -> Result<String, TxError>

创建保存点（用于嵌套事务）

返回自动生成的保存点名（格式 sp_<N>，N 单调递增）。

H-8 修复：检查嵌套深度，超过 options.max_nesting_depth 时返回 TxError::MaxNestingDepthExceeded。

L-5 修复：补充示例文档

示例

// 在外层事务中创建保存点
let sp = tx.savepoint().await?;
// 执行一些操作
tx.execute("INSERT INTO orders (id) VALUES (1)").await?;
// 出错时回滚到保存点（不影响外层事务的其他操作）
tx.rollback_to_savepoint(&sp).await?;
// 不再需要保存点时释放
tx.release_savepoint(&sp).await?;

pub async fn rollback_to_savepoint(&mut self, name: &str) -> Result<(), TxError>

回滚到保存点

name 必须是合法的保存点名称（仅 ASCII 字母/数字/下划线，且不以数字开头）。 通常使用 savepoint() 返回的名称。

pub async fn release_savepoint(&mut self, name: &str) -> Result<(), TxError>

释放保存点

name 必须是合法的保存点名称（仅 ASCII 字母/数字/下划线，且不以数字开头）。 通常使用 savepoint() 返回的名称。

pub async fn take_connection(&mut self) -> Result<Box<dyn Connection>, TxError>

取出底层连接（用于归还到连接池）

仅在事务已 commit/rollback 后才能调用，否则返回 NotActive 错误。 重复调用返回 ConnectionTaken 错误。

典型用法：

tx.commit().await?;
let conn = tx.take_connection().await?;
pool.release(conn).await;

pub fn options(&self) -> &TransactOptions

获取事务选项

Trait Implementations

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.