Configuration de la base de données

Configuration des connexions à la base de données Laravel, séparation lecture/écriture, connexions multiples, exécution SQL, écoute des requêtes et transactions.

​

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.

​

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', '[e-mail]']);

$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.