Updated June 2026. Tested on Laravel 13 and PHP 8.4.

A reader once described a common setup to me: a master database and a replica that copies from it. The default connection points at the master, but sometimes they wanted a query, a model, or even a migration to run against the replica instead. That is easy in Laravel. You define more than one connection, then tell each piece of code which one to use.

Step 1: Define the connections

Open config/database.php. Under connections, you already have one entry. Copy it and give the copy a new name. Here we keep a mysql_master and add a mysql_replica, each reading its own .env keys.

'default' => env('DB_CONNECTION', 'mysql_master'),

'connections' => [

    'mysql_master' => [
        'driver'    => 'mysql',
        'host'      => env('DB_HOST', '127.0.0.1'),
        'database'  => env('DB_DATABASE', 'master_db'),
        'username'  => env('DB_USERNAME', 'root'),
        'password'  => env('DB_PASSWORD', ''),
        'charset'   => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
    ],

    'mysql_replica' => [
        'driver'    => 'mysql',
        'host'      => env('DB_REPLICA_HOST', '127.0.0.1'),
        'database'  => env('DB_REPLICA_DATABASE', 'replica_db'),
        'username'  => env('DB_REPLICA_USERNAME', 'root'),
        'password'  => env('DB_REPLICA_PASSWORD', ''),
        'charset'   => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
    ],

],

Add the matching DB_REPLICA_* keys to your .env. The default stays mysql_master, so anything that does not say otherwise uses the master.

Step 2: Target a connection

From an Eloquent model

Set the $connection property to make a model always use a given connection.

class Report extends Model
{
    protected $connection = 'mysql_replica';
}

Or switch a single query at runtime with on.

$report = Report::on('mysql_replica')->find(1);

From the query builder

Name the connection up front.

use Illuminate\Support\Facades\DB;

$users = DB::connection('mysql_replica')->table('users')->where('id', 1)->get();

From a migration

A migration can build its tables on a specific connection with Schema::connection.

public function up(): void
{
    Schema::connection('mysql_replica')->create('reports', function (Blueprint $table) {
        $table->id();
        $table->string('title');
        $table->timestamps();
    });
}

From a stored procedure

Calls through the DB facade take a connection the same way.

$rows = DB::connection('mysql_replica')->select('CALL monthly_summary(?)', [$month]);

In every case, leaving the connection out falls back to the default, mysql_master.

Setting a connection on the fly

You are not limited to connections written into the config file. You can define one at runtime and switch to it, which is exactly how a database per tenant works. If that is your goal, see the dedicated guide on building a database per tenant SaaS, which covers configuring a connection on the fly with config(), DB::purge and DB::reconnect.

So multiple databases in Laravel come down to two steps: define the connections, then point each model, query, migration or procedure at the one it needs. Questions welcome in the comments.