MysqlTransaction

MysqlTransaction

功能

MySQL 事务句柄。事务内 SQL 按顺序复用同一个底层事务，适合需要原子提交或回滚的多条 SQL。

语法

方法

方法	参数	返回值	说明
query(sql)	sql:String	MysqlTransaction	设置事务内 SQL。
bind(value1, value2, ...)	任意值	MysqlTransaction	追加绑定参数。
all()	无	Array	执行查询并返回多行。
one()	无	Object/empty	执行查询并返回单行；没有结果返回 empty。
exec()	无	Object	执行写入 SQL，返回 SQL 执行统计对象；字段见下方。
commit()	无	Bool	提交事务，成功返回 true。
rollback()	无	Bool	回滚事务，成功返回 true。
close()	无	Bool	活动事务会回滚并关闭；已经结束时返回 false。
status()	无	String	返回 active、committed、rolled_back、closed 或 failed。
sql(render_binds)	Bool，可选	String	返回 SQL 预览文本；默认渲染绑定参数。

返回值

类型	说明
MysqlTransaction	query/bind 返回新的轻量构建器，但共享同一个事务状态。
Array	all 返回行对象数组。行对象字段见下方“查询行对象字段”。
Object/Empty	one 有结果时返回单行对象；没有结果时返回 `empty`。行对象字段见下方“查询行对象字段”。
Object	exec 返回 SQL 执行统计对象。字段见下方“exec 返回对象字段”。
Bool	commit、rollback、close 的状态结果。
String	status 或 sql 的文本结果。

查询行对象字段

all() 和 one() 返回的行对象是动态对象，字段来自 SQL 结果集列名。

字段	类型	必定存在	说明
任意列名	Any	否	数据库返回的列值。字段名是结果集列名；字段不存在时读取结果为 `empty`。数据库 NULL 返回 `null`。

exec 返回对象字段

字段	类型	必定存在	说明
total	Int	是	本次事务内 `exec()` 处理的绑定行数。事务内暂不支持 `binds()` 批量执行，因此当前固定为 `1`。
rows_affected	Int	是	数据库报告的受影响行数。
last_insert_id	Int	是	数据库报告的最后插入 ID。
batch_count	Int	是	实际拆分执行的批次数。事务内暂不支持批量执行，因此当前固定为 `1`。
batch_size	Int	是	当前执行的批大小。事务内暂不支持 `batch()`，因此当前为 `0`。
workers	Int	是	当前执行使用的并发工作数。事务内按顺序复用同一个底层事务，因此当前为 `1`。

代码示例

注意事项

不要并发复用同一个事务对象；事务执行期间再次使用会报错。
事务内暂不支持 binds、batch、workers 批量执行配置。
未 commit 的事务应调用 rollback 或 close；对象被丢弃时 SQLx 会尝试回滚，但脚本应显式关闭资源。
BT.stats().mysql.transactions_active 可用于观察当前活动事务数量。