ThinkPHP多数据库连接与模型操作完整教程

很多开发者在使用ThinkPHP进行多数据库操作时，会陷入一个误区：以为只要在模型里指定一个数据库名，或者框架能“智能”识别，就能轻松实现跨库查询。但现实往往很骨感——直接操作通常会换来一个冰冷的“Connection not found”错误。

问题的核心在于，ThinkPHP的多数据库连接机制是“配置驱动”的。它并非动态识别，而是要求你在config/database.php文件中，预先为每一个需要用到的数据库连接定义一个唯一的“钥匙”。这把“钥匙”，也就是配置数组的键名，是后续所有操作的门票。任何一个关键配置项的缺失，比如忘了写type，或者键名命名不规范，都会导致连接失败。

database.php 里怎么加第二个 MySQL 连接

添加第二个连接，可不是简单复制粘贴默认配置然后改个库名就万事大吉了。关键在于理解connections数组下的唯一键名机制。这个键名（例如'mysql_read'）是后续代码中调用的唯一标识。一个常见的坑是，复制了配置却忘了修改hostname或database，结果两个连接指向了同一个数据库，失去了分离的意义。

• 键名命名有讲究：像'mysql_write'、'mysql_read'这样的命名是常见做法。记住，键名只能包含小写字母和下划线，使用点号（如mysql.read）或大写字母都会导致框架无法识别。
• type字段必须显式声明：即使都是MySQL，每个连接配置里也必须明确写上'type' => 'mysql'。如果省略，框架可能会用默认的MySQL驱动类去尝试连接其他类型的数据库（如PostgreSQL），从而抛出类似Class 'PDO' not found的令人困惑的错误。
• 为只读连接加个保险：如果某个连接确定只用于查询，建议设置'write_master' => false。这可以防止一些关联操作意外触发写入请求。
• 字符集问题不容小觑：当主库和从库使用不同字符集（比如一个utf8mb4，一个gbk）时，务必在各自的配置中明确指定'charset'参数。否则，插入中文数据时可能会产生乱码或被截断。

Db::connect() 传什么参数才有效

这是另一个高频出错点。Db::connect()方法接受的参数，既不是数据库的名称，也不是模型类的名字，而必须是你在config/database.php的connections数组中定义的那个连接键名。传错了，Connection not found: xxx的异常就会立刻出现。

• 正确示例：Db::connect('mysql_read')。这行代码会加载对应配置，并返回一个使用该连接的新查询实例。
• 错误示例：Db::connect('user_db')（如果'user_db'这个键名未定义）、Db::connect('User')（误传模型名）、或者Db::connect(['hostname' => ...])（临时传入数组配置，在高并发下可能导致数据库连接数被耗尽）。
• 需要明确的是，调用Db::connect()并不会改变全局的默认数据库连接。每次需要进行跨库查询时，都需要显式地调用它。同时，它也不能用于在运行时动态修改已创建连接的主机、端口等参数，这些都属于静态配置，只能在项目配置文件中预设。

模型类里 $connection = 'xxx' 的实际作用边界

在模型类中设置protected $connection = 'mysql_read'属性，确实能让该模型的查询走向指定的数据库。但它的生效范围是有限制的：这个属性仅在模型类首次初始化时被读取一次，后续重载配置并不会刷新它。更重要的是，它不支持跨库的JOIN关联查询。

• 关联查询的陷阱：假设User模型设置了$connection = 'mysql_read'，那么User::select()会使用只读库。但是，当你使用User::with('profile')::select()进行关联查询时，其中的profile关联模型会使用它自身定义的$connection属性（可能是主库），而不会自动跟随User模型路由到只读库。
• 手动分离查询：要实现同时查询主库的user表和从库的log表，通常需要手动进行两次独立的查询操作：Db::connect('mysql')->table('user')->...; 和 Db::connect('mysql_log')->table('log')->...;，然后在业务逻辑层进行数据组装。
• 关于原生跨库JOIN：MySQL本身支持跨同一数据库实例的不同库进行JOIN（如SELECT * FROM db1.user JOIN db2.log），但这需要账号有相应权限。ThinkPHP的ORM并不会自动为你拼接数据库前缀，要实现这种查询，要么手写完整的原生SQL语句，要么使用Db::query()方法。

同步数据时为什么不能用 limit + offset 分页

在编写跨库数据同步脚本时，使用limit 5000 offset 10000这类方式进行分页遍历是一个危险的选择。因为同步过程往往耗时较长，在此期间，源表的数据可能发生变化（如删除旧行、插入新行），导致基于偏移量的分页出现数据漏同步或重复处理的问题。

• 推荐按主键范围分片：更稳妥的方式是依据表的主键（通常是自增ID）进行范围划分，例如WHERE id BETWEEN ? AND ?。可以先查询出表的min(id)和max(id)，然后动态划分区间进行处理。
• 批量写入提升性能：在将数据写入目标库时，务必使用insertAll()方法进行批量插入，坚决避免在循环中使用单条insert()。后者会带来巨大的事务开销和性能瓶颈。
• 设计断点续传机制：对于重要的同步任务，建议设计一个检查点（checkpoint）表，记录每次成功同步的最后一条数据ID。这样即使同步过程意外中断，重启后也可以从断点处继续，保障数据的完整性。

最后，还有一个配置上的细节容易踩坑：当你使用环境变量（如.env文件）来覆盖数据库配置时，变量名的格式必须正确。对于多数据库连接，应该使用database.connections.mysql_read.hostname这样的二维点语法格式，而不是database_mysql_read_hostname。如果格式写错，环境变量里的值是不会生效的，程序仍然会读取代码中的配置，这可能引发生产环境配置错乱的严重问题。