Laravel数据库连接故障切换日志记录，如何记录主从切换事件？

本文共计1139个文字，预计阅读时间需要5分钟。

在默认情况下，Laravel 不会主动记录数据库连接切换，你只需配置读写分离即可。以下是一个简单的配置示例：

核心是监听 Illuminate\Database\Events\ConnectionEstablished 事件，它在每次新连接真正建立时触发（不是每次 DB::connection() 调用，而是底层 PDO 实例创建后）。但注意：它不区分“主”还是“从”，只告诉你连上了哪个配置名。

• 在 AppServiceProvider::boot() 中注册监听器，别放错生命周期
• 通过 $event->connection->getConfig('name') 拿到当前连接名（比如 mysql-read-1），再比对预设的从库列表来判断是否属于切换
• 避免在监听器里做耗时操作（如写文件、发 HTTP 请求），否则拖慢查询；建议用队列或异步 logger
• 别监听 StatementPrepared 或 QueryExecuted —— 它们发生在连接已建立之后，无法反映“切换”本身

如何识别一次真正的“从库切换”而非复用连接

Laravel 的连接池和连接复用机制会让同一个连接被反复使用，所以不能单靠“事件触发次数”判断是否切换。关键要看连接实例的唯一标识是否变化。

ConnectionEstablished 事件对象里没有直接暴露连接 ID，但你可以用 spl_object_hash($event->connection->getPdo()) 获取底层 PDO 对象哈希值。只要这个哈希变了，就说明换了物理连接。

• 维护一个全局静态变量（如 self::$lastReadHash）缓存上一次从库连接哈希
• 仅当当前连接名属于从库配置 且 哈希值不同，才视为有效切换
• 主库连接也触发该事件，但一般不需要记录“主库切换”，除非你做了多主故障转移
• 注意：测试时用 DB::purge('read') 强制清空连接池，否则很难复现切换

为什么 DB::reconnect() 不会触发 ConnectionEstablished

因为 DB::reconnect() 是手动重建连接，但它内部调用的是 resetConnection() + reconnect()，并不走标准连接工厂流程，所以绕过了事件分发机制。

如果你依赖手动重连做故障恢复（比如检测到 SQLSTATE[HY000] [2002] 后调用 reconnect()），那这部分切换完全不会被上面的监听捕获。

• 必须在调用 reconnect() 前后手动打点日志，例如：Log::debug('Manually reconnecting to read connection', ['name' => 'mysql-read-2'])
• 更稳妥的做法是封装自己的 SafeReadConnection 类，在执行查询前检查连接可用性，失败则先 purge() 再 connection()，这样能兜住事件
• 别指望 DB::connection()->getPdo() 抛异常就自动触发切换日志——PDO 连接异常通常发生在 query 阶段，那时已经晚了

日志内容里必须包含哪些字段才够排障

光写“切换到了 mysql-read-2”意义不大。线上出问题时，你需要快速定位是不是切换导致了后续超时或数据不一致。

至少记录这五项：connection_name、pdo_hash、timestamp、previous_hash（如果有）、stack_trace（可选，但建议在 debug 模式下开启）。

• 用 Log::channel('database')->info() 单独分流日志，别混进 laravel.log，否则查起来太吵
• 不要记录完整 SQL 或参数，避免敏感信息泄露；如果真需要上下文，记下 debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2) 就够了
• 注意 Laravel 9+ 的日志上下文限制（默认 32KB），大数组或长 trace 会被截断，提前 json_encode 并 substr 控制长度

切换日志真正的难点不在记录，而在“什么时候算一次有效切换”——连接复用、连接池、PDO 懒初始化这些细节叠加起来，很容易漏掉静默复用或误报冷启动。留心 pdo_hash 和配置名的双重校验，比任何文档都管用。