ThinkPHP主从切换_ThinkPHP模型主从配置教程【方法】

ThinkPHP主从配置：三个条件缺一不可，否则全部流量直连主库

很多开发者以为，在ThinkPHP里配置主从数据库，无非就是在配置文件中加一个read数组。但实际情况是，这个想法过于乐观了。ThinkPHP的主从切换机制，必须同时满足三个硬性条件才能生效：启用部署开关、开启读写分离、主从配置结构完整。只要漏掉其中任何一项，那么所有通过Db::name()发起的查询，都会一股脑地走向默认连接，也就是你的主库，所谓的读写分离和负载均衡根本不会发生。

database.php 里 deploy => 1 是启动读写分离的总闸门

这里有个关键认知需要纠正：ThinkPHP 6并不会主动去扫描你的配置里有没有read或write节点。只有当'deploy' => 1这个开关存在且为真时，框架底层的读写分离逻辑才会被加载。它和'rw_separate' => true是父子关系——如果deploy这个总闸门没打开，rw_separate连上场的机会都没有。

实践中，下面两种错误配置非常普遍：

• default配置指向了一个具体的连接名（比如'mysql'），但在'mysql'这个连接的配置数组里，却忘了写'deploy' => 1。结果就是，所有查询都走向主库，你精心配置的read列表被完全忽略。
• 把deploy错误地写在了default配置的顶层，例如'default' => ['deploy' => 1, 'type' => 'mysql']。这会导致TP启动时报错，或者直接静默降级，不启用任何分离功能。

那么，正确的位置在哪里？答案很明确：deploy必须嵌套在具体的数据库连接配置内部。来看一个标准的写法：

“PHP免费学习笔记（深入）”立即学习；

'connections' => [
    'mysql' => [
        'deploy' => 1,
        'rw_separate' => true,
        'read' => [['hostname' => 'sla ve1'], ['hostname' => 'sla ve2']],
        'write' => ['hostname' => 'master'],
        // 其他通用参数（type/database/username等）
    ]
]

read 和 write 的结构差异极易踩坑

配置的结构细节是另一个“坑点”。read节点支持数组套数组的形式，用于配置多个从库，ThinkPHP会从中随机选择一个进行查询。而write节点则只允许一个单独的配置数组，指向唯一的主库。如果你把write也写成数组套数组，框架会直接抛出Invalid write database config异常。

下面这些典型错误，你很可能遇到过：

• 'write' => [['hostname' => 'master']] —— 多了一层中括号，报错。正确写法是['hostname' => 'master']。
• 'read' => ['hostname' => 'sla ve1'] —— 虽然语法上合法，TP也会将其当作一个“仅包含一个元素的从库列表”来处理，但这在语义上非常模糊，容易在后续维护时产生混淆。
• 从库之间的用户名、密码或数据库名不同 —— 这种情况下，read列表里的每一个子数组都必须携带完整的连接参数，不能只补充hostname，否则连接会失败。

为了安全起见，建议采用下面这种清晰、完整的写法：

'read' => [
    [
        'hostname' => 'sla ve1.example.com',
        'database' => 'app_db',
        'username' => 'ro_user',
        'password' => 'xxx'
    ],
    [
        'hostname' => 'sla ve2.example.com',
        'database' => 'app_db',
        'username' => 'ro_user',
        'password' => 'yyy'
    ]
]

哪些查询会绕过从库、强制走主库

即使配置完全正确，也并非所有SELECT查询都会乖乖地走向从库。ThinkPHP 6的路由判断基于SQL语义和执行上下文，在以下几种情况下，查询会强制走主库：

• 使用了显式锁：例如->lock(true)或->lock('FOR UPDATE')。
• 执行的原生SQL语句中包含FOR UPDATE或LOCK IN SHARE MODE这类锁定子句。
• 当前操作处于一个数据库事务中（哪怕只是调用了Db::startTrans()之后的一个普通select()）。
• 在查询链中显式调用了->master()方法（例如Db::name('user')->master()->select()）。

另外需要特别注意：使用with()进行的关联查询，其默认行为是混合走主库和从库。如果关联表跨了不同的数据库，或者主从之间存在延迟，就可能导致查询结果不一致。这并非ThinkPHP的bug，而是分布式架构下为了性能不得不做的权衡。

Db::connect() 和 Db::name() 的行为边界

理解这两个方法的区别，对于灵活控制连接至关重要。Db::name('user')这种方式，永远绑定的是default配置所指向的那个连接（比如'mysql'），它的读写路由完全由该连接配置内的'rw_separate'规则控制。而Db::connect('mysql_sla ve')则是一种“直连模式”，它直接绕过框架内置的所有路由逻辑，后续所有操作都固定使用你指定的这个连接，不再参与任何负载均衡或自动分离。

所以，可以得出几条实用准则：

• 如果想临时查询某个特定的从库（例如做数据校验或报表生成），可以使用Db::connect('xxx')，但你需要自己管理好这些额外的连接定义。
• 如果希望某次读操作也强制走主库（比如写入后需要立刻进行强一致性读取），必须在查询链中加上->master(true)，不要指望主从同步的那点延迟能为你兜底。
• 避免在模型内部硬编码Db::connect()调用，否则在测试或切换环境时，维护会变得异常困难。

最后，也是最容易被忽略的一点：主从延迟是业务层必须直面的现实。ThinkPHP本身并不提供延迟感知或自动重试机制。这意味着，如果你执行了一个insert操作，然后立刻发起一个select查询，只要没有显式指定->master(true)，那么有很大概率会读到旧数据。这一点，必须在业务设计之初就充分考虑。