# 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，返回 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`。 |

## 代码示例

```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` 可用于观察当前活动事务数量。