> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Info>
  Cette page couvre les prérequis de connexion. Pour les requêtes pratiques, consultez le [Query Builder](/fr/query-builder), pour la gestion de schéma les [migrations](/fr/migrations), et pour le peuplement initial le [seeding](/fr/seeding).
</Info>

## 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`.

```mermaid theme={null}
flowchart TD
    A[".env"] --> B["config/database.php"]
    B --> C["Connexion par défaut"]
    B --> D["connections.mysql"]
    B --> E["connections.pgsql"]
    B --> F["connections.sqlite"]
    C --> G["Façade DB / Query Builder / Eloquent"]
```

```php theme={null}
// 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`.

```ini theme={null}
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.

```php theme={null}
'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`.

<Tip>
  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.
</Tip>

## 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`.

```php theme={null}
'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.

```php theme={null}
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()`.

```php theme={null}
use Illuminate\Support\Facades\DB;

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

```mermaid theme={null}
flowchart LR
    A["DB::connection('mysql')"] --> B["DB principale"]
    C["DB::connection('pgsql')"] --> D["DB d'analytique"]
    E["DB::connection('sqlite')"] --> F["DB en fichier local"]
```

## Exécution de requêtes SQL

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

```php theme={null}
use Illuminate\Support\Facades\DB;

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

DB::insert('insert into users (name, email) values (?, ?)', ['Taylor', 'taylor@example.com']);

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

<Warning>
  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.
</Warning>

## Écoute des requêtes

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

```php theme={null}
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.

```php theme={null}
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`.

```php theme={null}
DB::transaction(function () {
    // ...
}, attempts: 5);
```

Pour un contrôle manuel, utilisez `beginTransaction` / `rollBack` / `commit`.

```php theme={null}
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

<Card title="Query Builder" icon="table" href="/fr/query-builder">
  Découvrez comment construire des requêtes en toute sécurité avec la configuration de connexion.
</Card>

<Card title="Migrations" icon="hammer" href="/fr/migrations">
  Apprenez à versionner le schéma de votre base de données.
</Card>

<Card title="Seeding" icon="seedling" href="/fr/seeding">
  Alimentez votre base avec des données de développement et de test de manière reproductible.
</Card>


## Related topics

- [Socialite - Laravel Bluesky](/fr/packages/laravel-bluesky/socialite.md)
- [Installation](/fr/installation.md)
- [Migrations de base de données](/fr/migrations.md)
- [Seeding de base de données](/fr/seeding.md)
- [Tests de base de données](/fr/database-testing.md)