Hyperf 配置多数据源需在 config/autoload/databases.php 中定义多个连接（如 default 和 slave），并在模型中通过 $connection 属性指定连接名；也可运行时用 on() 或 DB::connection() 动态切换。

Hyperf 中配置多数据源，核心是定义多个数据库连接配置，并在模型或服务中指定使用哪个连接。最简可行示例只需修改 config/autoload/databases.php 并在模型中声明 $connection 属性。

1. 配置多个数据库连接

在 config/autoload/databases.php 中添加多个连接配置，例如主库（default）和从库（slave）：

return [
    'default' => [
        'driver' => env('DB_DRIVER', 'mysql'),
        'host' => env('DB_HOST', 'localhost'),
        'port' => env('DB_PORT', 3306),
        'database' => env('DB_DATABASE', 'hyperf'),
        'username' => env('DB_USERNAME', 'root'),
        'password' => env('DB_PASSWORD', ''),
        'charset' => env('DB_CHARSET', 'utf8mb4'),
        'collation' => env('DB_COLLATION', 'utf8mb4_unicode_ci'),
        'prefix' => env('DB_PREFIX', ''),
        'pool' => [
            'min_connections' => 1,
            'max_connections' => 10,
            'connect_timeout' => 10.0,
            'wait_timeout' => 3.0,
            'heartbeat' => -1,
            'max_idle_time' => (float) env('DB_MAX_IDLE_TIME', 60),
        ],
    ],
    'slave' => [
        'driver' => env('DB_SLAVE_DRIVER', 'mysql'),
        'host' => env('DB_SLAVE_HOST', '192.168.1.100'),
        'port' => env('DB_SLAVE_PORT', 3306),
        'database' => env('DB_SLAVE_DATABASE', 'hyperf_slave'),
        'username' => env('DB_SLAVE_USERNAME', 'reader'),
        'password' => env('DB_SLAVE_PASSWORD', ''),
        'charset' => env('DB_SLAVE_CHARSET', 'utf8mb4'),
        'collation' => env('DB_SLAVE_COLLATION', 'utf8mb4_unicode_ci'),
        'prefix' => env('DB_SLAVE_PREFIX', ''),
        'pool' => [
            'min_connections' => 1,
            'max_connections' => 5,
            'connect_timeout' => 10.0,
            'wait_timeout' => 3.0,
            'heartbeat' => -1,
            'max_idle_time' => 60.0,
        ],
    ],
];

2. 在模型中指定连接

创建模型时，通过 $connection 属性指定使用哪个数据库配置名：

Hyperframes Creative

HyperFrames视频非动画创意指导，包括设计规范（frame.md/design.md）处理、配色、字体设计、旁白及节奏规划等。

下载

namespace App\Model;

use Hyperf\DbConnection\Model\Model;

class User extends Model
{
    protected $connection = 'default'; // 使用 default 连接
}

class Log extends Model
{
    protected $connection = 'slave'; // 使用 slave 连接（如只读查询）
}

3. 运行时动态切换连接（可选）

不改模型也能临时切库，适合同一模型不同场景：

• 查询时用从库：User::on('slave')->where('id', 1)->first();
• 事务必须走主库：DB::connection('default')->transaction(fn () => ...);
• 手动获取连接实例：DB::connection('slave');

4. 环境变量建议（.env）

配合环境变量更灵活：

DB_DRIVER=mysql
DB_HOST=localhost
DB_DATABASE=hyperf_db
DB_USERNAME=root
DB_PASSWORD=

DB_SLAVE_DRIVER=mysql
DB_SLAVE_HOST=192.168.1.100
DB_SLAVE_DATABASE=hyperf_slave_db
DB_SLAVE_USERNAME=reader
DB_SLAVE_PASSWORD=123456

不需要额外安装扩展或写中间件，Hyperf 的 DbConnection 组件原生支持多连接。只要配置名一致、模型指定正确，就能自动路由到对应数据库。