# MysqlTransaction

## 功能

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

## 语法

```bt
tx = mysql(dsn).begin()
tx.query(sql).bind(value).exec()
tx.commit()
```

## 方法

| 方法 | 参数 | 返回值 | 说明 |
| ------ | ------ | ------ | ------ |
| query(sql) | sql:String | MysqlTransaction | 设置事务内 SQL。 |
| bind(value1, value2, ...) | 任意值 | MysqlTransaction | 追加绑定参数。 |
| all() | 无 | Array | 执行查询并返回多行。 |
| one() | 无 | Object/empty | 执行查询并返回单行；没有结果返回 empty。 |
| exec() | 无 | Object | 执行写入 SQL，返回 rows_affected 等统计字段。 |
| 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 返回新的轻量构建器，但共享同一个事务状态。 |
| Bool | commit、rollback、close 的状态结果。 |
| String | status 或 sql 的文本结果。 |

## 代码示例

```bt
db = mysql('mysql://user:pass@127.0.0.1/test')
tx = db.begin()
tx.query('update user set name=? where id=?').bind('BT', 1).exec()
status = tx.status()
tx.rollback()

// 输出：active
echo(status)
```

## 注意事项

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