change database connection in laravel model

change database connection in laravel model

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

Stefan Bogdanescu

Founder & Senior Architect

Changing Database Connections in a Laravel Model

In Laravel, the default behavior for an Eloquent model is to connect to the default database configuration defined in your config/database.php file. This is convenient for monolithic applications where all tables reside in a single schema. However, scenarios often arise where you need a specific model to interact with a secondary or external database instance without affecting the rest of your application.

The snippet provided from the Laravel 4.2 era illustrates a common point of confusion:

<?php
class McibModel extends Eloquent {
    /**
      * The database table used by the model.
      *
      * @var string
      */
    protected $table = 'agencies';
}

While this code correctly defines the table name, it does not explicitly specify which database connection to use. If your config/database.php contains a connections array with keys like mysql, pgsql, and perhaps an external_db, you cannot simply assume that changing $table will automatically switch the driver or host. By default, the model will attempt to query against the default connection defined in the configuration file.

To direct this model specifically to an external database, you must explicitly set the $connection property within the model class. This is a static property that overrides the global default for that specific class.

Here is how you should modify the McibModel class:

<?php

class McibModel extends Eloquent {
    /**
      * The database table used by the model.
      *
      * @var string
      */
    protected $table = 'agencies';

    // Explicitly define the connection name
    protected $connection = 'external_db';
}

When you configure your config/database.php file, ensure that the key you are referencing (e.g., 'external_db') exists in the connections array. It does not need to be the last entry; the order in the configuration file is irrelevant. The connection name is simply a string key that maps to an associative array containing driver, host, database, and other necessary credentials.

Configuration Requirements

For this approach to work, your database configuration must be set up beforehand. A typical configuration block for the external connection might look like this:

'connections' => [
    'mysql' => [
        'driver'   => 'mysql',
        'host'     => '127.0.0.1',
        'database' => 'main_app',
        // ... other settings
    ],

    'external_db' => [
        'driver'   => 'mysql',
        'host'     => 'external-server.com',
        'database' => 'agencies_schema',
        'username' => 'app_user',
        'password' => 'secret_password',
        'charset'  => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix'   => '',
    ],
],

Once the configuration is in place and the model property is set, Laravel will route all queries for McibModel to the external_db connection while leaving the default connection untouched for your other models.

Trade-offs and Best Practices

This method works well for single-model scenarios or when you are creating a dedicated migration runner for an external database. However, there are architectural considerations to keep in mind.

If you are building a large-scale application where multiple models need to interact with the same external database, defining $connection on every model class can become repetitive and difficult to maintain. In such cases, it is often better to define the connection name directly in the config/database.php file under a specific key (e.g., 'default_external') and then reference that key consistently.

Furthermore, be aware of transaction limitations. If your external database uses a different driver or version than your primary application database, you may encounter issues with ACID compliance or transaction locking if you attempt to join tables across connections in a single query. Eloquent generally handles cross-database joins poorly; it is safer to fetch data from the external connection and process it in memory before performing operations on the main database.

Finally, remember that this behavior relies on the version of Laravel you are running. While the $connection property has been consistent across versions including 4.2, later versions introduced ConnectionResolverInterface which allows for more complex resolution strategies if needed. For standard external database access, the static property remains the most direct and reliable solution.

Our network