在 CakePHP 中定义多个数据库数据源需在 config/app.php 的 Datasources 配置项中预先声明各别名（如 'default'、'logs'、'tenant_123'），运行时通过 Table::setConnection() 或 Query::connection() 显式指定，不可动态修改配置数组或期望自动重连。
如何在 CakePHP 中定义多个数据库数据源
CakePHP 的多数据源支持依赖于 config/app.php（或 config/app_local.php）中 Datasources 配置项，每个键名就是一个数据源别名。你不能只靠运行时改配置数组来切换——框架在启动时已将这些配置解析并注册进连接管理器。
必须显式声明所有可能用到的数据源，哪怕某些只在特定场景下启用。比如要支持生产库、日志库、客户分片库，就得提前配好：
'Datasources' => [
'default' => [
'className' => 'Cake\Database\Connection',
'driver' => 'Cake\Database\Driver\Mysql',
'host' => 'localhost',
'username' => 'app',
'password' => '***',
'database' => 'main_db',
// ...
],
'logs' => [
'className' => 'Cake\Database\Connection',
'driver' => 'Cake\Database\Driver\Mysql',
'host' => 'log-server',
'database' => 'audit_logs',
// ...
],
'tenant_123' => [
'className' => 'Cake\Database\Connection',
'driver' => 'Cake\Database\Driver\Mysql',
'host' => 'shard-01',
'database' => 'client_123',
// ...
],
],
- 别名（如
tenant_123）必须是合法 PHP 标识符，不能含点、短横或动态变量插值 - 不要在
Datasources里写条件逻辑或调用函数——配置文件是静态解析的 - 敏感信息（如密码）建议通过环境变量注入，例如
'password' => env('DB_LOGS_PASSWORD', '')
运行时切换数据源的两种可靠方式
CakePHP 不允许在请求中途“替换”已初始化的默认连接，但支持为具体表或查询临时指定数据源。核心机制是绑定表类与连接，或在查询时覆盖连接实例。
最常用且安全的方式是：在 Table 类构造时传入连接别名，或在查询构建时用 connection() 显式指定。
立即学习“PHP免费学习笔记（深入）”；
- 对固定用途的表（如日志表），直接在 Table 类中硬编码连接：
// src/Model/Table/AuditLogsTable.php
class AuditLogsTable extends Table
{
public function initialize(array $config): void
{
$this->setTable('audit_logs');
$this->setConnection('logs'); // ← 关键：绑定到 'logs' 数据源
}
}
- 对需要动态决定数据源的场景（如按租户 ID 切库），避免在 Table 类中写死，改用查询时指定：
$tenantId = '123';
$connectionName = 'tenant_' . $tenantId;
$query = $this->Articles->find()
->connection($connectionName); // ← 运行时传入别名
// 或更底层一点：
$connection = ConnectionManager::get($connectionName);
$query = $this->Articles->find()->getConnection($connection);
- 注意：
connection()必须在execute()或all()前调用，否则无效 - 如果用了自定义查询类（如继承
Query），需确保它没缓存连接实例
为什么不能直接修改 ConnectionManager::getConfig() 并期望生效
有人尝试在运行时调用 ConnectionManager::getConfig('default') 获取配置数组、改掉 database 字段再塞回去——这完全无效。因为 ConnectionManager 在第一次调用 get() 时就根据原始配置创建了 Connection 实例，并缓存起来；后续 get() 返回的是同一个对象，不是重新读配置生成的。
- 修改配置数组不影响已创建的连接对象，也不会触发重连
- 强行 new Connection(...) 并试图替换内部引用，会破坏事务上下文和连接池行为
- 若真需要同一张表在不同连接间复用，应让该表类支持构造时传参，而不是改全局配置
常见错误：事务跨数据源失败或查询静默降级
当你在事务中混用多个数据源时，CakePHP 默认不支持分布式事务。如果代码写了：
$connection = ConnectionManager::get('default');
$connection->begin(); // ← 只对 default 生效
$this->Articles->find()->connection('logs')->all(); // ← 这个查询不在事务中！
$connection->commit();
结果是：日志查询独立执行、无法回滚，且无任何警告。这是最容易被忽略的隐性 bug。
- 跨数据源操作必须明确放弃事务一致性，或自行实现两阶段提交（极少必要）
- 使用
connection()后，所有关联加载（contain()）、保存（save()）、删除都走指定连接，但前提是关联表也正确设置了连接 - 如果某个关联表没设
setConnection()，它仍会走默认连接，导致“部分查 A 库、部分查 B 库”的混乱
动态切库不是魔法开关，它把责任交还给开发者：每个表、每次查询、每个事务边界，都得主动声明意图。漏掉一处，就可能查错库、写错表、丢掉数据。
