# mysql MySQL 标准库

## 功能

mysql(dsn) 创建 MySQL 查询构建器，支持 SQL 设置、普通绑定、批量绑定、批量执行、查询多行、查询单行、写入执行和 SQL 预览。

## API 列表

| API | 说明 |
| ------ | ------ |
| [mysql.query](/docs/mysql/query) | 设置当前 MySQL 对象的 SQL 文本。 |
| [mysql.bind](/docs/mysql/bind) | 追加一组普通绑定参数。 |
| [mysql.binds](/docs/mysql/binds) | 追加多行批量绑定参数。 |
| [mysql.batch](/docs/mysql/batch) | 设置批量 exec 的每批行数。 |
| [mysql.workers](/docs/mysql/workers) | 设置批量 exec 的并发工作数。 |
| [mysql.begin](/docs/mysql/begin) | 开启一个 MySQL 事务并返回事务句柄。 |
| [MysqlTransaction](/docs/mysql/transaction) | 事务句柄，支持事务内 query/bind/all/one/exec/commit/rollback/close。 |
| [mysql.all](/docs/mysql/all) | 执行查询并返回多行结果。 |
| [mysql.one](/docs/mysql/one) | 执行查询并返回单行结果。 |
| [mysql.exec](/docs/mysql/exec) | 执行不需要返回结果集的 SQL。普通绑定执行一次；binds 批量配置会按 batch/workers 执行。 |
| [mysql.sql](/docs/mysql/sql) | 返回当前 SQL 的调试文本。 |

## 示例

```bt
db = mysql('mysql://user:pass@127.0.0.1/test')
result = db.query('select * from user where id=?').bind(1).sql()

// 输出：select * from user where id=1
print result
```

## 注意事项

- all/one/exec 会复用进程级 I/O runtime 并同步等待数据库结果。
- 默认启用 MySQL 普通查询连接池，按 DSN 分组复用；池状态可通过 `BT.stats().mysql` 查看，统计不会泄露 DSN 密码。
- begin 会开启一个事务并独占一条连接；事务完成后必须显式调用 commit、rollback 或 close。
- `binds().exec()` 批量执行仍按本次 `workers()` 创建临时连接池，避免全局池改变批量并发边界。
- all/one 会拒绝 binds、batch、workers，避免批量配置被静默误用。

MySQL 普通查询连接池默认配置：

| 环境变量 | 默认值 | 说明 |
| ------ | ------ | ------ |
| BT_MYSQL_POOL | true | 是否启用普通查询全局连接池。 |
| BT_MYSQL_POOL_LIMIT | 16，最大 256 | 最多保留的 DSN 分组数量。 |
| BT_MYSQL_POOL_MIN_CONNECTIONS | 0 | 每个连接池最小连接数。 |
| BT_MYSQL_POOL_MAX_CONNECTIONS | 8，最大 1024 | 每个连接池最大连接数。 |
| BT_MYSQL_POOL_IDLE_TTL_MS | 300000 | 连接池空闲保留时间，单位毫秒；0 表示不按空闲时间淘汰。 |
| BT_MYSQL_CONNECT_TIMEOUT_MS | 5000 | 获取连接的超时时间，单位毫秒。 |
| BT_MYSQL_QUERY_TIMEOUT_MS | 30000 | 单次 SQL 调用同步等待超时时间，单位毫秒。 |
| BT_MYSQL_SLOW_MS | 0 | 慢 MySQL 调用日志阈值，单位毫秒；0 表示关闭。 |