Configuration de la base de données

Introduction

Laravel prend en charge officiellement les bases de données suivantes.

MySQL / MariaDB
PostgreSQL
SQLite
SQL Server

Vous utilisez la même configuration de connexion, que ce soit avec du SQL brut, le Query Builder ou l’ORM Eloquent.

Cette page couvre les prérequis de connexion. Pour les requêtes pratiques, consultez le Query Builder, pour la gestion de schéma les migrations, et pour le peuplement initial le seeding.

Configuration

Les paramètres de base de données sont centralisés dans config/database.php. Vous choisissez la connexion par défaut avec default et définissez les détails de chaque connexion dans 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', ''),
    ],
],

Configurez au minimum les variables suivantes dans .env.

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

Avec SQLite, définissez DB_CONNECTION=sqlite et le chemin de DB_DATABASE.

Séparation lecture / écriture

Pour séparer les lectures (SELECT) et les écritures (INSERT / UPDATE / DELETE) sur des hôtes différents, configurez read et write dans la même connexion.

'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', ''),
],

Avec sticky à true, les lectures effectuées après une écriture dans la même requête sont bloquées sur la connexion write.

En cas de latence de réplication, activer sticky réduit le risque de lire des données obsolètes juste après une écriture.

Éviter les lectures obsolètes dans les requêtes suivantes

sticky ne s’applique qu’au sein d’une même requête. Pour lire les données fraîchement écrites également dans les requêtes suivantes de la même session, ajoutez le middleware PreventStaleDatabaseReads au groupe de middleware web.

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

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

Le middleware enregistre dans la session les écritures sur la connexion de base de données par défaut. Par défaut, les requêtes effectuées dans les 2 secondes suivant une écriture utilisent la connexion write pour les lectures sur cette connexion. Pour modifier cette durée, utilisez for.

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

Ce middleware dépend de la session : il doit donc s’exécuter après le middleware StartSession. Il n’affecte pas les lectures des autres sessions ni des autres connexions de base de données.

Lire temporairement depuis la connexion d’écriture

Pour forcer les lectures d’un callback sur la connexion write, utilisez la méthode usingWritePdo de la connexion.

use Illuminate\Support\Facades\DB;

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

Cela s’applique aussi aux requêtes Eloquent et aux relations qui utilisent la même connexion dans le callback. À la fin du callback, le paramètre de lecture de la connexion est restauré, qu’une exception ait été levée ou non.

Connexion PostgreSQL avec pool

Si vous utilisez un service PostgreSQL managé fournissant un pooling de connexions en mode transaction (type PgBouncer), configurez les options pooled et direct.

'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'),
    ]),
],

Avec pooled activé, Laravel effectue le routage automatiquement.

Opération	Connexion utilisée
Requêtes applicatives	pooled (émulation des prepared statements activée automatiquement)
Migrations / `db:wipe` / `db:show` / `db:table`	direct (automatique)
`php artisan db`	direct (par défaut), passe à pooled avec `--pooled`

Pour utiliser explicitement la connexion direct dans le code, ajoutez le suffixe ::direct au nom de connexion.

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

Connexions multiples

Vous pouvez définir plusieurs connexions dans config/database.php et basculer avec DB::connection().

use Illuminate\Support\Facades\DB;

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

Exécution de requêtes SQL

La façade DB propose des méthodes dédiées par type de requête.

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');

Ne concaténez jamais les entrées utilisateur directement dans une chaîne SQL. Utilisez toujours des paramètres liés pour éviter les injections SQL.

Écoute des requêtes

Pour suivre le SQL exécuté, enregistrez DB::listen() dans la méthode boot() d’un service provider.

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

Pour traiter plusieurs mises à jour comme une unité atomique, utilisez DB::transaction(). En cas d’exception, Laravel effectue automatiquement le rollback.

use Illuminate\Support\Facades\DB;

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

Si vous avez besoin de retenter en cas de deadlock, spécifiez attempts.

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

Pour un contrôle manuel, utilisez 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;
}

Prochaines étapes

Query Builder

Découvrez comment construire des requêtes en toute sécurité avec la configuration de connexion.

Migrations

Apprenez à versionner le schéma de votre base de données.

Seeding

Alimentez votre base avec des données de développement et de test de manière reproductible.

Architecture

Base de données

Eloquent

Sécurité

Événements

E-mails et notifications

Paiements

Traitement asynchrone

Communication temps réel

Planification

Cache et optimisation

Internationalisation

Fichiers et stockage

Débogage et supervision

Console et CLI

Performance

Frontend

Développement IA

Environnement de développement

Configuration de la base de données

Introduction

Configuration

Séparation lecture / écriture

Éviter les lectures obsolètes dans les requêtes suivantes

Lire temporairement depuis la connexion d’écriture

Connexion PostgreSQL avec pool

Connexions multiples

Exécution de requêtes SQL

Écoute des requêtes

Transactions

Prochaines étapes

Query Builder

Migrations

Seeding

​Introduction

​Configuration

​Séparation lecture / écriture

​Éviter les lectures obsolètes dans les requêtes suivantes

​Lire temporairement depuis la connexion d’écriture

​Connexion PostgreSQL avec pool

​Connexions multiples

​Exécution de requêtes SQL

​Écoute des requêtes

​Transactions

​Prochaines étapes

Query Builder

Migrations

Seeding

Introduction

Configuration

Séparation lecture / écriture

Éviter les lectures obsolètes dans les requêtes suivantes

Lire temporairement depuis la connexion d’écriture

Connexion PostgreSQL avec pool

Connexions multiples

Exécution de requêtes SQL

Écoute des requêtes

Transactions

Prochaines étapes