ThinkPHP读写分离配置与主库强制读取操作指南

许多开发者在配置ThinkPHP6读写分离功能时，常常遇到一个典型问题：各项参数看似都已正确设置，但数据库查询请求却全部指向了主库，未能按预期分流至从库。实际上，ThinkPHP框架的读写分离机制并非“配置即生效”，其运作依赖于几个关键的配置开关与特定的调用方法。同样，强制查询走主库也并非简单调用某个方法即可，关键在于理解其生效范围与链式调用的连续性。

读写分离功能必须显式开启

一个普遍的认知误区是，只要在database.php配置文件中填写了多个数据库地址或定义了‘read’数组，系统便会自动实现读写分离。事实并非如此。在ThinkPHP6中，要真正启用并触发读写分离，必须同时满足以下三项核心条件，缺一不可：

• ‘deploy’ => 1：这是启用多服务器部署模式的总开关。只有将此参数设置为1，后续的读写分离逻辑才会被框架加载并初始化。
• ‘rw_separate’ => true：明确开启读写自动分离的功能开关。此参数控制是否根据SQL操作类型（读/写）自动选择数据库连接。
• ‘read’配置项非空且为有效数组：例如‘read’ => [[‘host’ => ‘192.168.1.10’]]。如果‘read’配置为空数组、null或非数组格式，分离功能将不会生效。

其中，‘deploy’ => 1这一条件尤其容易被开发者忽略。若未开启此选项，整个读写分离模块将不会启动，后续的所有相关配置都将失去作用。

Db::connect()方法与默认连接的区别

清晰理解不同数据库连接方式之间的差异，是避免配置失效的关键。

使用Db::connect(‘mysql’)这种方式，是显式指定一个已在database.php配置文件的connections节点下定义好的命名连接。此连接独立于全局默认连接行为，不参与框架内置的读写分离路由决策，其读写行为完全由该连接自身的配置决定。

而诸如Db::name(‘user’)或Db::table(‘user’)这类调用，则会始终使用default配置所指向的默认数据库连接。此时，查询请求是否会路由至从库，完全取决于default连接配置中是否开启了‘rw_separate’以及‘read’配置是否有效。

这里存在一个常见误区：开发者可能先调用Db::connect(‘sla ve_read’)获取一个指向从库的连接实例，然后试图复用此实例进行查询，例如写成Db::connect(‘sla ve_read’); Db::table(‘user’)->select();。实际上，第二条语句中的->table()方法会重新绑定到默认连接，导致前一条语句指定的连接失效。正确的链式调用写法应为：Db::connect(‘sla ve_read’)->table(‘user’)->select()。

强制查询走主库的两种可靠方法

在需要读取主库最新数据的业务场景下，例如写入操作后立即进行查询，强制查询走主库是必要的。但若方法使用不当，同样会导致失效。具体采用哪种方式，需根据业务上下文决定。

• 单次查询强制一致性：使用Db::master()->table(‘user’)->where(‘id’, 1)->find()。此方法的关键在于，master()方法必须位于链式调用的起始位置，并且后续的所有查询操作（如where、find）都必须在此方法返回的新连接实例上连续调用。
• 事务内的读写混合操作：在数据库事务中，为了保证数据的一致性，所有数据库操作（包括SELECT查询）默认都会使用主库连接。因此，只需正常开启事务即可，无需额外指定：Db::transaction(function () { Db::table(‘user’)->find(); })。

需要警惕的错误写法是：Db::master(); Db::table(‘user’)->find();。第一个master()调用确实返回了一个指向主库的新连接实例，但此实例未被后续代码使用；第二个Db::table()又创建了一个新的查询构建器实例，该实例仍然指向默认连接，因此查询可能仍会路由至从库。

如何调试验证读写分离是否生效

如何验证你的读写分离配置确实已生效并正确路由？仅依靠getLastSql()方法打印出的SQL语句是无法判断的，因为它只显示SQL字符串本身，无法告知该语句最终是在主库还是从库上执行。

真正有效的验证与调试方法，通常有以下两种：

• 直接监控数据库连接：在从库数据库服务器上执行SHOW PROCESSLIST命令，然后筛选出来自你应用服务器IP地址的连接，观察是否有PHP应用发起的SELECT查询连接。这是最直接、最可靠的证据。
• 在框架底层添加日志：在ThinkPHP框架的think\db\Connection.php文件的connect()方法中添加日志记录，打印出每次建立连接时的$config[‘hostname’]（连接的数据库地址）和$isRead（是否为读操作）标志。这能清晰地展示每次查询的路由决策过程。

如果发现从库的进程列表中始终看不到SELECT查询连接，则应优先检查以下几个方面：‘read’配置是否为空或无效、‘deploy’ => 1是否遗漏、查询是否意外地在事务中执行，或者是否使用了锁语句（例如lock(true)），这些情况都会导致查询被强制导向主库。