MySQL 配置与限额

连接与 TLS

connect_options 配置 host、数值 port（默认 3306）、username、password、可选 database 和默认 10 秒的 timeout。连接时限覆盖 DNS 解析、建连、TLS 协商和 MySQL 认证。

默认 tls_mode::required。客户端先发送 MySQL SSLRequest，再启动 TLS，验证证书信任和 DNS/IP 身份；服务端不支持 TLS 时失败。ca_file 指定私有 CA 文件，否则使用默认信任路径。server_name 默认等于 host；覆盖它会改变验证的身份和 DNS SNI，不会改变连接地址，也不会关闭对端验证。

tls_mode::disabled 是显式明文选项，不允许明文完整密码认证；没有经过验证的 TLS 时，caching_sha2_password 完整认证请求会失败。认证哈希仍需要 OpenSSL。客户端不会自动降级 TLS，也不提供 RSA 公钥密码交换。

支持 caching_sha2_password 和 mysql_native_password，以及服务端要求的受支持认证切换。未知插件和不支持的认证交互会明确失败，不提供 mysql_clear_password、sha256_password、MFA 或任意插件加载。

查询与队列限额

命令投递到 IO 线程前，先预留请求数量和实际保留的输入容量。拒绝时释放大块数据，通过完成回调报告 queue_full；IO 线程被阻塞时，也不能在计数器之外无限积压请求。这些限额不约束调用者自行持有的数据，也不代表进程内存总上限。

请求按 FIFO 执行，同一条连接同时只有一条命令在传输。查询、预处理、执行、关闭语句和事务辅助接口均接受 query_options。结果完整保存在内存中。协议错误、不支持的后续结果、结果超限或未完成响应会关闭连接，避免在报文边界不确定时继续复用。

字段类型

field_value 拥有以下类型之一：表示 SQL NULL 的 std::monostate、有符号或无符号 64 位整数、double、std::string、date_value、datetime_value 或 time_value。文本查询结果和预处理二进制结果都依据列元数据解码。DECIMAL、BIT、JSON 和字节／字符串字段保留原字节，不隐式损失精度或进行字符集转换。时间值保留服务端各组成部分，不自动转换时区。

预处理参数同样使用这些类型，通过二进制编码发送，不进行 SQL 转义。不支持的字段编码和非法取值范围会明确失败。读取前先检查 variant 当前持有的类型。

取消与结果未知

每条命令返回可传给 cancel(id) 的 request_id。取消或超时发生在排队阶段时，仅移除该请求，不影响当前命令的回复。已经发送的执行中命令取消或超时，会关闭会话，避免剩余回复被误认为后续命令的回复。

失败命令可能已经执行时，connection_result.outcome_unknown 为 true。例如等待 COMMIT 回复期间连接中断，事务可能已经提交，只是客户端没有收到成功回复。尚未发送的排队命令会失败，不会重放。应用需要依据操作语义和持久化业务标识决定恢复方式，客户端不会隐式重试写入。

code 区分本地、协议、传输和服务端错误；transport_error、server_code、sql_state 与 message 保留可用诊断。完整、正常的服务端 ERR 回复可能允许继续复用连接；非法或不完整响应会关闭连接。并非所有服务端错误都表示写入结果未知。

连接池限额与重置

pool_options 提供 max_connections（8）、max_waiters（1024）、io_threads（1）、acquire_timeout（5 秒）、reset_timeout（5 秒）及 connection 配置。IO context 和线程属于网络库，连接共用池内运行资源；提高连接上限不会隐式为每条连接创建线程。

async_acquire 返回可传给 pool.cancel(id) 的获取请求 ID，并支持覆盖超时。租约独占一条连接，命令 ID 通过 lease.cancel(id) 取消。获取请求限额包含正在等待和建连的请求。替换连接时不重放命令或事务。

归还时限从 release() 或租约析构请求归还时开始，包含在途回调排空、COM_RESET_CONNECTION 和数据库恢复。MySQL 重置不会恢复所选数据库，连接池会通过正确引用名称的 USE 切回配置的数据库，再允许复用。若配置的数据库为空，每次归还都丢弃连接，因为使用者选择数据库后，重置无法恢复成「未选择数据库」。重置、恢复失败，超过时限或连接不健康时也会丢弃。

租约析构和 release() 只发起归还，不会阻塞调用线程；连接会在已提交回调返回后才允许复用。该会话的预处理语句在重置或丢弃后失效，不能交给下一位借用者。空租约或已移动租约没有执行器，会同步拒绝并返回请求 ID 0。连接池的永久准入门仍开放时，仍持有控制信息的已归还租约在库管理的 IO 线程上完成拒绝；永久准入门关闭后，保留租约在调用线程同步拒绝，请求 ID 为 0。close() 异步终止连接池，返回不代表回调已经排空。

语句、重置与生命周期

prepared_statement 是可复制、共享所有权的不透明句柄，绑定一代连接和具体会话。副本共用关闭状态。async_close 发送没有回复的 COM_STMT_CLOSE；完成成功表示客户端写入完成，不是服务端确认。最后一个句柄释放时，若会话仍有效，会安排相同的资源清理。

async_reset 执行 COM_RESET_CONNECTION，成功后使现有语句句柄失效，并重置服务端会话与事务状态。不要跨重置、重连保留语句，也不要在其他连接上使用。普通连接的事务辅助接口不提供独占事务所有权。

每条独立连接使用由网络库管理的一个 IO context 和线程。已受理操作的回调在该 IO 线程上恰好执行一次，不得抛异常或阻塞。空租约的拒绝，以及永久准入门关闭后的请求拒绝，会在调用线程同步调用 handler；这些拒绝回调可以向调用方传播异常。close() 异步请求取消，返回不代表回调已经排空。回调捕获的应用对象需要存活到回调完成；支持在回调中析构连接，无需调用者管理 IO 线程。客户端不会自动重连或重放命令。