需监听 Illuminate\Database\Events\ConnectionEstablished 事件，在 AppServiceProvider::boot() 中通过 spl_object_hash($event->connection->getPdo()) 比对 PDO 哈希值与预设从库名，仅当二者均变化时记录含 connection_name、pdo_hash、timestamp、previous_hash、stack_trace 的结构化日志。
怎么让 Laravel 在主从切换时自动记日志
默认情况下，Laravel 不会主动记录数据库连接切换行为，哪怕你配置了读写分离，DB::connection('read') 换到另一个从库，也不会留下痕迹。要捕获这个动作，得靠监听底层事件。
核心是监听 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 和配置名的双重校验，比任何文档都管用。
