Database configuration

Introduction

Laravel officially supports the following databases:

MySQL / MariaDB
PostgreSQL
SQLite
SQL Server

You can use the same connection configuration whether you’re using raw SQL, the query builder, or the Eloquent ORM.

This page covers the prerequisites of database connections. For practical queries, see Query Builder. For schema management, see Migrations. For initial data population, see Seeding.

Configuration

Database configuration is centralized in config/database.php. You choose the default connection name with default, and define the details of each connection under connections.

// config/database.php
'default' => env('DB_CONNECTION', 'sqlite'),

'connections' => [
    'mysql' => [
        'driver' => 'mysql',
        'host' => env('DB_HOST', '127.0.0.1'),
        'port' => env('DB_PORT', '3306'),
        'database' => env('DB_DATABASE', 'laravel'),
        'username' => env('DB_USERNAME', 'root'),
        'password' => env('DB_PASSWORD', ''),
    ],
],

In .env, at minimum set the following:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=app
DB_USERNAME=app_user
DB_PASSWORD=secret

When using SQLite, set DB_CONNECTION=sqlite and the path in DB_DATABASE.

Separating read and write connections

If you want to separate reads (SELECT) and writes (INSERT / UPDATE / DELETE) onto different hosts, configure read and write within the same connection.

'mysql' => [
    'driver' => 'mysql',
    'read' => [
        'host' => ['10.0.0.10', '10.0.0.11'],
    ],
    'write' => [
        'host' => ['10.0.0.20'],
    ],
    'sticky' => true,

    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'laravel'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
],

Setting sticky to true pins reads after a write to the write connection within the same request.

In setups where replicas lag behind, enabling sticky reduces the risk of reading stale data immediately after a write.

Preventing stale reads on subsequent requests

sticky only applies within the same request. To read freshly written data on subsequent requests in the same session as well, add the PreventStaleDatabaseReads middleware to the web middleware group.

use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Foundation\Http\Middleware\PreventStaleDatabaseReads;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->web(append: [
        PreventStaleDatabaseReads::class,
    ]);
})

The middleware records writes to the default database connection in the session. By default, requests made within 2 seconds of a write use the write connection for reads on that connection. To change the duration, use for.

$middleware->web(append: [
    PreventStaleDatabaseReads::for(5),
]);

This middleware depends on the session, so it must run after the StartSession middleware. It does not affect reads from other sessions or other database connections.

Reading from the write connection temporarily

To pin reads inside a callback to the write connection, use the connection’s usingWritePdo method.

use Illuminate\Support\Facades\DB;

$users = DB::connection()->usingWritePdo(
    fn ($connection) => $connection->table('users')->get(),
);

This also applies to Eloquent and relationship queries that use the same connection inside the callback. When the callback finishes, the connection’s read setting is restored whether or not an exception was thrown.

Pooled PostgreSQL connections

When using a managed PostgreSQL service that provides transaction-mode connection pooling (such as PgBouncer), configure the pooled and direct options.

'pgsql' => [
    'driver' => 'pgsql',
    // ...
    'pooled' => env('DB_POOLED', false),
    'direct' => array_filter([
        'host' => env('DB_DIRECT_HOST'),
        'port' => env('DB_DIRECT_PORT'),
        'username' => env('DB_DIRECT_USERNAME'),
        'password' => env('DB_DIRECT_PASSWORD'),
        'sslmode' => env('DB_DIRECT_SSLMODE'),
    ]),
],

When pooled is enabled, Laravel automatically routes traffic.

Operation	Connection used
Application queries	pooled (emulated prepares are enabled automatically)
Migrations / `db:wipe` / `db:show` / `db:table`	direct (automatic)
`php artisan db`	direct (default), switch to pooled with `--pooled`

If you want to explicitly use the direct connection in application code, add the ::direct suffix to the connection name.

DB::connection('pgsql::direct')->statement('create extension if not exists "uuid-ossp"');

Multiple database connections

You can define multiple connections in config/database.php and switch between them with DB::connection().

use Illuminate\Support\Facades\DB;

$users = DB::connection('sqlite')->select('select * from users');
$pdo = DB::connection('pgsql')->getPdo();

Executing SQL queries

The DB facade has dedicated methods for each query type.

use Illuminate\Support\Facades\DB;

$users = DB::select('select * from users where active = ?', [1]);

DB::insert('insert into users (name, email) values (?, ?)', ['Taylor', '[email protected]']);

$affected = DB::update('update users set votes = 100 where name = ?', ['Taylor']);

$deleted = DB::delete('delete from sessions where user_id = ?', [1]);

DB::statement('drop table temporary_imports');

Never concatenate user input directly into SQL strings. Always use binding parameters to prevent SQL injection.

Query listening

When you want to track the SQL that is executed, register DB::listen() in a service provider’s boot() method.

use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Support\Facades\DB;

public function boot(): void
{
    DB::listen(function (QueryExecuted $query) {
        logger()->debug('SQL executed', [
            'sql' => $query->toRawSql(),
            'time_ms' => $query->time,
        ]);
    });
}

Transactions

To treat multiple updates as a single unit, use DB::transaction(). Laravel automatically rolls back if an exception is thrown.

use Illuminate\Support\Facades\DB;

DB::transaction(function () {
    DB::update('update users set votes = 1');
    DB::delete('delete from posts where archived = 1');
});

If you need deadlock retries, you can specify attempts.

DB::transaction(function () {
    // ...
}, attempts: 5);

If you want manual control, use beginTransaction / rollBack / commit.

DB::beginTransaction();

try {
    DB::update('update accounts set balance = balance - 100 where id = ?', [1]);
    DB::update('update accounts set balance = balance + 100 where id = ?', [2]);

    DB::commit();
} catch (\Throwable $e) {
    DB::rollBack();
    throw $e;
}

Next steps

Query Builder

Learn how to safely build queries using your connection configuration.

Migrations

Learn how to version-control the schema of your connected database.

Seeding

Learn how to populate development and test data in a reproducible way.

Architecture

Database

Eloquent

Security

Events

Mail and Notifications

Payments

Asynchronous Processing

Real-time Communication

Scheduling

Cache and Optimization

Internationalization

Files and Storage

Debugging and Monitoring

Console and CLI

Performance

Frontend

AI Development

Development Environment

Introduction

Configuration

Separating read and write connections

Preventing stale reads on subsequent requests

Reading from the write connection temporarily

Pooled PostgreSQL connections

Multiple database connections

Executing SQL queries

Query listening

Transactions

Next steps

Query Builder

Migrations

Seeding

​Introduction

​Configuration

​Separating read and write connections

​Preventing stale reads on subsequent requests

​Reading from the write connection temporarily

​Pooled PostgreSQL connections

​Multiple database connections

​Executing SQL queries

​Query listening

​Transactions

​Next steps

Query Builder

Migrations

Seeding

Introduction

Configuration

Separating read and write connections

Preventing stale reads on subsequent requests

Reading from the write connection temporarily

Pooled PostgreSQL connections

Multiple database connections

Executing SQL queries

Query listening

Transactions

Next steps