Multiple Database Connection in Laravel

Laravel has built-in support for multiple database connections. This tutorial explains how to configure and use Multiple Database Connection in Laravel application in a simple way, especially for beginners. Think of each database like a separate notebook. One notebook may store users, and another notebook may store employees. Laravel can read from both notebooks if we tell it where each one is.

Prerequisites

• PHP installed
• Composer installed
• Laravel project created
• Access to two or more MySQL databases

Step 1: Configure Database Connections

Open the .env file and add the credentials for each database.

DB_CONNECTION=mysql

# Primary Database
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=main_database
DB_USERNAME=root
DB_PASSWORD=password

# Secondary Database
DB_SECOND_HOST=127.0.0.1
DB_SECOND_PORT=3306
DB_SECOND_DATABASE=second_database
DB_SECOND_USERNAME=root
DB_SECOND_PASSWORD=password

Simple explanation

The .env file is where we keep private settings like database names, usernames, and passwords.
Here, we are telling Laravel:

• use one database as the main database
• use another database as the second database

Step 2: Update config/database.php

Add a new connection inside the connections array.

'connections' => [

    'mysql' => [
        'driver' => 'mysql',
        'host' => env('DB_HOST', '127.0.0.1'),
        'port' => env('DB_PORT', '3306'),
        'database' => env('DB_DATABASE', 'forge'),
        'username' => env('DB_USERNAME', 'forge'),
        'password' => env('DB_PASSWORD', ''),
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix' => '',
        'strict' => true,
    ],

    'mysql_second' => [
        'driver' => 'mysql',
        'host' => env('DB_SECOND_HOST', '127.0.0.1'),
        'port' => env('DB_SECOND_PORT', '3306'),
        'database' => env('DB_SECOND_DATABASE', 'forge'),
        'username' => env('DB_SECOND_USERNAME', 'forge'),
        'password' => env('DB_SECOND_PASSWORD', ''),
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix' => '',
        'strict' => true,
    ],

],

Simple explanation

This file tells Laravel how to connect to each database.

• mysql is the default connection
• mysql_second is the new connection we added

So now Laravel knows there are two different databases available.

Step 3: Using Multiple Database Connections

This is the part that may feel confusing at first, so let’s make it very simple.

What is happening here?

When you write:

$users = DB::table('users')->get();

Laravel uses the default database.

When you write:

$employees = DB::connection('mysql_second')
    ->table('employees')
    ->get();

Laravel uses the second database.

Easy way to understand it

Imagine you have two classrooms:

• Classroom 1 = main database
• Classroom 2 = second database

If you want to ask a question in Classroom 1, you go there normally.

If you want to ask a question in Classroom 2, you must say which classroom you want.

That is exactly what DB::connection('mysql_second') does. It tells Laravel:
“Use the second database for this query.”

Query the Primary Database

$users = DB::table('users')->get();

This gets data from the main database.

Query the Secondary Database

$employees = DB::connection('mysql_second')
    ->table('employees')
    ->get();

This gets data from the second database.

Beginner tip

If you are just starting, remember this simple rule:

• no connection(...) = default database
• connection('mysql_second') = second database

Step 4: Create Models for Different Databases

Models help us work with database tables in a cleaner way.

Primary Database Model

class User extends Model
{
    protected $table = 'users';
}

Secondary Database Model

class Employee extends Model
{
    protected $connection = 'mysql_second';

    protected $table = 'employees';
}

Usage:

$employees = Employee::all();

Simple explanation

A model is like a helper class for a table.

• User model works with the main database
• Employee model works with the second database because we told it to use mysql_second

So when you call Employee::all(), Laravel knows which database to use.

Step 5: Running Migrations on a Specific Database

Create a migration:

php artisan make:migration create_employees_table

Run migration on the secondary database:

php artisan migrate --database=mysql_second

Simple explanation

A migration is like a set of instructions for creating or changing a table.

If you want the table to be created in the second database, you must tell Laravel to use that database with:

--database=mysql_second

Step 6: Transactions on a Specific Database

DB::connection('mysql_second')->transaction(function () {
    DB::connection('mysql_second')
        ->table('employees')
        ->insert([
            'name' => 'John Doe'
        ]);
});

Step 7: Example Controller

namespace App\Http\Controllers;

use App\Models\User;
use App\Models\Employee;

class DashboardController extends Controller
{
    public function index()
    {
        $users = User::all();

        $employees = Employee::all();

        return response()->json([
            'users' => $users,
            'employees' => $employees
        ]);
    }
}

Simple explanation

This controller gets data from both databases:

• User::all() gets users from the main database
• Employee::all() gets employees from the second database

Then it sends both results back as JSON.

Best Practices

1. Use separate models for each database.
2. Store credentials only in the .env file.
3. Use meaningful connection names.
4. Avoid cross-database joins when possible.
5. Use database-specific transactions.
6. Test connection failures and error handling.

Beginner tip

If you are new, start small:

• first connect to one database
• then add the second database
• then test queries one by one

This makes it much easier to understand.

Troubleshooting

Connection Not Found

Database connection [mysql_second] not configured.

Verify that the connection name exists in config/database.php.

Authentication Errors

Access denied for user.

Check username, password, and database permissions.

Configuration Cache Issues

After changing database configuration, run:

php artisan config:clear
php artisan cache:clear

Conclusion

Laravel makes it easy to work with multiple MySQL databases by defining multiple connections in config/database.php and selecting the desired connection using models or the DB facade.

For beginners, the main idea is simple:

• one Laravel project can talk to more than one database
• each database needs its own connection name
• you choose the database by using that connection name

This is useful for multi-tenant applications, legacy database integrations, and data separation requirements.