在调试多数据库连接时使用 mysqli::debug 的策略

M66 2025-05-13

在进行 PHP 开发时，尤其是在一个应用中处理多个数据库连接时，调试数据库操作可能会变得复杂。PHP 的 mysqli::debug 方法是一个较少被提及但非常有用的调试工具，特别适合用来分析数据库连接、执行语句、甚至查看底层的网络活动。

本篇文章将详细介绍如何在调试多个数据库连接时有效使用 mysqli::debug 方法，并结合示例代码加以说明。

什么是 mysqli::debug 方法？

mysqli::debug() 是 MySQLi 扩展中提供的一个静态方法，用于向 MySQL 客户端库发送调试信息，主要用于开发和调试过程中。这个函数不会返回任何内容，它的主要作用是将调试信息写入客户端库所配置的调试文件中。

要使其生效，必须在 my.cnf 或 my.ini 中启用调试支持（通常通过 client 部分中的 debug=d:t:o,/tmp/client.trace 配置），然后使用该方法触发记录。

mysqli::debug("d:t:o,/tmp/client.trace");

这将把调试信息写入 /tmp/client.trace。

多数据库连接下的调试策略

当你的应用中连接了多个数据库时，例如主数据库与多个只读副本，调试就需要更加有针对性。以下是一些推荐的策略。

1. 给每个连接单独设置标识

你可以封装数据库连接过程，为每一个连接加上标识名，并在输出日志中区分来源。

function connect_to_db($label, $host, $user, $pass, $db) {
    mysqli::debug("d:t:o,/tmp/{$label}_trace.log"); // 设置每个连接的调试文件
    $conn = new mysqli($host, $user, $pass, $db);
    if ($conn->connect_error) {
        die("连接失败 ({$label}): " . $conn->connect_error);
    }
    return $conn;
}

$main_db = connect_to_db("main", "localhost", "root", "password", "main_db");
$replica_db = connect_to_db("replica", "localhost", "root", "password", "replica_db");

2. 用日志配合调试追踪

虽然 mysqli::debug 是底层调试信息，但配合 PHP 的日志输出，可以形成完整的调试链路。

mysqli::debug("d:t:o,/tmp/replica_trace.log");
$replica_conn = new mysqli("localhost", "user", "pass", "replica_db");

if ($replica_conn->connect_error) {
    error_log("连接副本数据库失败: " . $replica_conn->connect_error);
} else {
    error_log("连接副本数据库成功: " . $replica_conn->host_info);
}

你可以使用如 http://m66.net/log-viewer 来搭建日志查看界面，快速定位问题。

3. 设置统一入口来控制调试开关

在开发或测试环境中，你可能不希望每次都手动调用 mysqli::debug，这时候可以用环境变量或配置文件控制是否开启调试。

if (getenv("DB_DEBUG") === "true") {
    mysqli::debug("d:t:o,/tmp/debug_trace.log");
}

在 .env 文件中添加：

DB_DEBUG=true

4. 使用 MYSQLI_REPORT_ALL 报错级别

结合 mysqli_report() 可以更好地捕捉错误：

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
mysqli::debug("d:t:o,/tmp/debug_trace.log");

$conn = new mysqli("localhost", "user", "pass", "some_db");

这将抛出异常而不是静默失败，让你更容易在代码层面追踪问题。

mysqli::debug