How to use multiple databases in Laravel

How to use multiple databases in Laravel

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Handling Multiple and Heterogeneous Databases in Laravel

When your application outgrows a single MySQL instance, you often find yourself needing to query across different sources. This might mean pulling historical data from an older archive, reading configuration from a Redis store, or eventually supporting reports that aggregate metrics from a PostgreSQL system while your core app runs on MySQL. The specific scenario of combining heterogeneous database systems—where the source differs from the target—is a common architectural evolution, yet Laravel's default configuration assumes a single connection per environment file.

To address this, you don't necessarily need to switch frameworks. Laravel provides the flexibility to manage multiple databases and even different drivers through its connection management system. The core mechanism relies on defining additional connections in your config/database.php file rather than relying on a single default connection. This approach allows you to maintain distinct configurations for MySQL, PostgreSQL, or other SQL dialects without rewriting your application's ORM logic.

You can define a new connection by specifying the driver, host, database name, username, and password within the connections array. For example, if you need to access a legacy system using Oracle while keeping your primary app on MySQL, you simply register the oracle connection in the configuration file. Laravel then treats these as distinct entities, allowing you to switch contexts via the database facade or service container.

return [
    'default' => env('DB_CONNECTION', 'mysql'),
    
    // Primary application database
    '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,
            'engine' => null,
        ],

        // Heterogeneous source for reports (e.g., PostgreSQL or Oracle)
        'reports_source' => [
            'driver' => 'pgsql', 
            'host' => env('REPORTS_HOST', 'report-db.internal'),
            'database' => env('REPORTS_DATABASE'),
            'username' => env('REPORTS_USERNAME'),
            'password' => env('REPORTS_PASSWORD'),
            'charset' => 'utf8',
            'prefix' => '',
            'schema' => 'public',
        ],
    ],
];

Once the connection is defined, you can access it directly through the DB facade by specifying the connection name. This allows your code to seamlessly query the heterogeneous source when generating reports, while continuing to use the default MySQL connection for standard operations.

use Illuminate\Support\Facades\DB;

// Query primary database
$users = DB::table('users')->get();

// Query heterogeneous report source
$legacyData = DB::connection('reports_source')
    ->table('legacy_metrics')
    ->whereYear('created_at', date('Y'))
    ->get();

A critical distinction to understand is that Laravel's Eloquent models are tightly coupled to a specific connection. You cannot easily map an existing model to a different database driver without significant refactoring. If you need to work with tables in the heterogeneous source, it is often cleaner to create a dedicated repository class or service that handles the reports_source connection explicitly. This keeps your domain models focused on the primary schema and isolates the complexity of cross-database queries.

When dealing with heterogeneous systems, performance and transactional consistency become major trade-offs. You generally cannot begin a transaction in MySQL and commit it across PostgreSQL within Laravel's standard session-based transaction management. If your report generation requires atomic operations across both databases, you will need to handle locking manually or accept eventual consistency by fetching the data and merging it in memory before returning the result set to the user.

For complex reporting scenarios where the source is truly heterogeneous, consider using Laravel's query builder with raw SQL for specific aggregation steps that cannot be translated via Eloquent. This gives you full control over how data is joined or filtered across different schemas without forcing the ORM to handle unsupported syntax.

If your team frequently manages these types of multi-source architectures, maintaining a library of connection patterns can save significant time. There are third-party packages available that extend Laravel's database capabilities to simplify cross-database queries, but they often come with version-specific constraints and require careful evaluation against your specific security and performance needs.

Our network