How to Use Multiple Databases in Laravel 13

To use multiple databases in Laravel 13, add a second connection to the connections array in config/database.php, put its credentials in .env, then pick it per query with DB::connection('name') or per model with the $connection property. Migrations can target it with php artisan migrate --database=name. The steps below use a MySQL default database and a second "legacy" database.

This is useful when you read from an older system, split reporting data from application data, or keep tenant data apart. It is not the same as read/write splitting, where one logical database has a primary and replicas. That is a separate feature configured with read and write keys inside one connection.

What do I need before I start?

• Laravel 13.x on PHP 8.3 or newer (the same approach works on Laravel 12).
• Two databases you can reach, for example two schemas on one MySQL server or two servers.
• Credentials for each.

Step 1: How do I add the second connection?

Open config/database.php. Copy the existing mysql entry inside connections, rename it, and point it to new environment variables:

'legacy' => [
    'driver' => 'mysql',
    'host' => env('LEGACY_DB_HOST', '127.0.0.1'),
    'port' => env('LEGACY_DB_PORT', '3306'),
    'database' => env('LEGACY_DB_DATABASE'),
    'username' => env('LEGACY_DB_USERNAME'),
    'password' => env('LEGACY_DB_PASSWORD'),
    'charset' => env('DB_CHARSET', 'utf8mb4'),
    'collation' => env('DB_COLLATION', 'utf8mb4_unicode_ci'),
    'prefix' => '',
    'strict' => true,
],

Use separate variable names, as above. If you reuse DB_HOST and friends, both connections silently point to the same database.

Step 2: What goes in .env?

DB_CONNECTION=mysql
DB_DATABASE=app

LEGACY_DB_HOST=127.0.0.1
LEGACY_DB_PORT=3306
LEGACY_DB_DATABASE=legacy_app
LEGACY_DB_USERNAME=legacy_user
LEGACY_DB_PASSWORD=change-me

Give each database its own user with only the rights it needs. If config is cached, run php artisan config:clear after editing.

Step 3: How do I run queries on the second connection?

The Laravel docs describe the connection method on the DB facade for exactly this. The name must match a key in config/database.php.

use Illuminate\Support\Facades\DB;

$rows = DB::connection('legacy')
    ->table('customers')
    ->where('active', 1)
    ->get();

DB::connection('legacy')->transaction(function () {
    DB::connection('legacy')
        ->table('customers')
        ->where('id', 1)
        ->update(['active' => 0]);
});

Queries without connection() keep using the default database. Transactions are per connection, so a transaction on the default connection does not cover writes on legacy.

Step 4: How do I point an Eloquent model at it?

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class LegacyCustomer extends Model
{
    protected $connection = 'legacy';
    protected $table = 'customers';
}

Now LegacyCustomer::query()->limit(10)->get() reads from the legacy database. I ran php -l on this model and the query snippets above to check the syntax. I did not run them against real databases.

How do I run migrations for the second database?

Run the migration against the other connection with the --database option:

php artisan migrate --database=legacy --path=database/migrations/legacy

Keep that connection's migrations in their own folder so a plain php artisan migrate does not apply them to the wrong database. You can also set protected $connection = 'legacy'; inside a migration class so it always targets that connection.

How do I check that it works?

1. Run php artisan db:show --database=legacy. It should print the legacy database name and its tables.
2. In php artisan tinker, run DB::connection('legacy')->getDatabaseName() and confirm it returns the legacy database name.
3. Run DB::getDefaultConnection() and confirm the default is unchanged.

Can I join tables across two connections?

Not with a single query builder join. Laravel sends each query to one connection. If both databases are on the same MySQL server, you can write a raw query that references other_db.table, but the user needs rights on both schemas. Otherwise, load data from one connection and combine it in PHP, or use a lookup by ID.

Eloquent relationships between models on different connections also need care. Define the relationship and eager load, but test it, since a query cannot join across servers.

What are the common mistakes?

• Same env variable names. Both connections then use identical credentials.
• Cached config. New values are ignored until you clear the cache.
• Migrations hitting the wrong database. Always pass --database and a dedicated path.
• Assuming one transaction covers both. Each connection has its own transaction.
• Over-privileged users. A legacy connection used for reporting should usually be read-only.
• Tests. Configure the second connection in your testing environment too, or tests will fail on the missing database.

FAQ

How many database connections can Laravel use?

There is no fixed limit in the framework. You can define as many entries as you need in config/database.php. Each open connection uses resources on the database server.

Can the second connection use a different database type?

Yes. Laravel supports MySQL, MariaDB, PostgreSQL, SQLite and SQL Server, and each connection sets its own driver.

How do I list or inspect another connection?

Use php artisan db:show --database=legacy, or Schema::connection('legacy')->getColumns('customers') in code.

References

• Laravel database: getting started
• Laravel migrations
• Eloquent ORM