# mysql MySQL standard library

## Function

mysql(dsn) creates a MySQL query builder that supports SQL settings, normal binding, batch binding, batch execution, querying multiple rows, querying a single row, writing execution and SQL preview.

## API List

| API | Description |
| ------ | ------ |
| [mysql.query](/en/docs/mysql/query) | Set the SQL text of the current MySQL object. |
| [mysql.bind](/en/docs/mysql/bind) | Append a set of common binding parameters. |
| [mysql.binds](/en/docs/mysql/binds) | Append multiple rows of batch binding parameters. |
| [mysql.batch](/en/docs/mysql/batch) | Set the number of rows per batch for batch exec. |
| [mysql.workers](/en/docs/mysql/workers) | Set the number of concurrent jobs for batch exec. |
| [mysql.begin](/en/docs/mysql/begin) | Start a MySQL transaction and return the transaction handle. |
| [MysqlTransaction](/en/docs/mysql/transaction) | Transaction handle, supports query/bind/all/one/exec/commit/rollback/close within the transaction. |
| [mysql.all](/en/docs/mysql/all) | Execute a query and return multiple rows of results. |
| [mysql.one](/en/docs/mysql/one) | Execute the query and return a single row of results. |
| [mysql.exec](/en/docs/mysql/exec) | Execute SQL that does not require returning a result set. Ordinary binding is executed once; binds batch configuration will be executed by batch/workers. |
| [mysql.sql](/en/docs/mysql/sql) | Returns the debugging text of the current SQL. |

## Examples

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

// Output: select * from user where id=1
print result
```

## Notes

- all/one/exec will reuse the process-level I/O runtime and wait for database results synchronously.
- MySQL common query connection pool is enabled by default and multiplexed by DSN group; the pool status can be viewed through `BT.stats().mysql`, and statistics will not reveal the DSN password.
- begin will open a transaction and exclusively own a connection; commit, rollback, or close must be explicitly called after the transaction is completed.
- `binds().exec()` batch execution still creates a temporary connection pool according to this `workers()` to avoid the global pool from changing the batch concurrency boundary.
- all/one will reject binds, batch, and workers to prevent batch configuration from being silently misused.

MySQL common query connection pool default configuration:

| Environment variable | Default value | Description |
| ------ | ------ | ------ |
| BT_MYSQL_POOL | true | Whether to enable the common query global connection pool. |
| BT_MYSQL_POOL_LIMIT | 16, maximum 256 | Maximum number of DSN packets to retain. |
| BT_MYSQL_POOL_MIN_CONNECTIONS | 0 | Minimum number of connections per connection pool. |
| BT_MYSQL_POOL_MAX_CONNECTIONS | 8, maximum 1024 | Maximum number of connections per connection pool. |
| BT_MYSQL_POOL_IDLE_TTL_MS | 300000 | Connection pool idle retention time, in milliseconds; 0 means no elimination based on idle time. |
| BT_MYSQL_CONNECT_TIMEOUT_MS | 5000 | Get the connection timeout, in milliseconds. |
| BT_MYSQL_QUERY_TIMEOUT_MS | 30000 | Synchronization wait timeout for a single SQL call, in milliseconds. |
| BT_MYSQL_SLOW_MS | 0 | Slow MySQL call log threshold, in milliseconds; 0 means closed. |