Datenbankkonfiguration

Einführung

Laravel unterstützt offiziell die folgenden Datenbanken:

MySQL / MariaDB
PostgreSQL
SQLite
SQL Server

Sie können dieselbe Verbindungskonfiguration mit Raw SQL, dem Query Builder oder dem Eloquent ORM verwenden.

Diese Seite behandelt die Grundlagen zu Datenbankverbindungen. Praxisnahe Queries finden Sie beim Query Builder, Schema-Management bei Migrations und das Einspielen initialer Daten bei Seeding.

Konfiguration

Die Datenbank-Konfiguration ist zentral in config/database.php gebündelt. Über default legen Sie die Standardverbindung fest, in connections konfigurieren Sie die einzelnen Verbindungen im Detail.

// 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 der .env sollten mindestens folgende Werte gesetzt sein:

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

Für SQLite setzen Sie DB_CONNECTION=sqlite und den Pfad in DB_DATABASE.

Trennung von Lese- und Schreibverbindung

Wenn Sie Lese- (SELECT) und Schreiboperationen (INSERT / UPDATE / DELETE) auf verschiedene Hosts verteilen möchten, konfigurieren Sie innerhalb derselben Verbindung read und write.

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

Mit sticky auf true werden Leseoperationen innerhalb desselben Requests nach einem Schreibvorgang auf die Schreibverbindung geleitet.

In Setups mit Replikations-Lag verringert sticky das Risiko, dass Sie direkt nach einem Schreibvorgang veraltete Daten lesen.

Veraltete Lesevorgänge auch in Folge-Requests verhindern

sticky wirkt nur innerhalb desselben Requests. Wenn Sie auch in nachfolgenden Requests derselben Session die gerade geschriebenen Daten lesen möchten, fügen Sie die Middleware PreventStaleDatabaseReads zur Middleware-Gruppe web hinzu.

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

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

Die Middleware speichert Schreibvorgänge auf die Standard-Datenbankverbindung in der Session. Standardmäßig verwenden Requests innerhalb von 2 Sekunden nach einem Schreibvorgang für Lesevorgänge auf dieser Verbindung die Schreibverbindung. Um die Dauer zu ändern, geben Sie for an.

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

Da diese Middleware von der Session abhängt, muss sie nach der Middleware StartSession ausgeführt werden. Lesevorgänge anderer Sessions oder anderer Datenbankverbindungen sind nicht betroffen.

Vorübergehend von der Schreibverbindung lesen

Um Lesevorgänge innerhalb eines Callbacks auf die Schreibverbindung zu fixieren, verwenden Sie die Methode usingWritePdo der Verbindung.

use Illuminate\Support\Facades\DB;

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

Das gilt auch für Eloquent- und Relationship-Abfragen, die innerhalb des Callbacks dieselbe Verbindung nutzen. Nach Ende des Callbacks wird die Lese-Einstellung der Verbindung wiederhergestellt, unabhängig davon, ob eine Exception aufgetreten ist.

Pooled PostgreSQL-Verbindungen

Wenn Sie einen verwalteten PostgreSQL-Dienst mit transaktionsbasiertem Connection-Pooling verwenden (etwa PgBouncer), konfigurieren Sie die Optionen pooled und 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'),
    ]),
],

Ist pooled aktiviert, kümmert sich Laravel automatisch um die richtige Zuordnung.

Operation	Verwendete Verbindung
Anwendungs-Queries	pooled (emulierte Prepared Statements werden automatisch aktiviert)
Migrationen / `db:wipe` / `db:show` / `db:table`	direct (automatisch)
`php artisan db`	direct (Standard); mit `--pooled` auf pooled umschalten

Wenn Sie in Anwendungscode explizit die Direct-Verbindung nutzen möchten, hängen Sie den Suffix ::direct an den Verbindungsnamen.

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

Mehrere Datenbankverbindungen

Sie können in config/database.php mehrere Verbindungen definieren und mit DB::connection() zwischen ihnen wechseln.

use Illuminate\Support\Facades\DB;

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

SQL-Abfragen ausführen

Die DB-Facade stellt für jeden Query-Typ eine dedizierte Methode bereit.

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

Konkatenieren Sie niemals Nutzereingaben direkt in einen SQL-String. Verwenden Sie unbedingt Bindungsparameter, um SQL-Injection zu verhindern.

Query Listening

Um ausgeführte SQL-Statements nachvollziehen zu können, registrieren Sie im boot() eines Service Providers einen Listener über DB::listen().

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,
        ]);
    });
}

Transaktionen

Um mehrere Änderungen als atomare Einheit zu behandeln, verwenden Sie DB::transaction(). Tritt eine Ausnahme auf, führt Laravel automatisch einen Rollback aus.

use Illuminate\Support\Facades\DB;

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

Ist ein automatischer Retry bei Deadlocks erforderlich, geben Sie attempts an.

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

Möchten Sie die Transaktion manuell steuern, verwenden Sie 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;
}

Nächste Schritte

Query Builder

Erfahren Sie, wie Sie Abfragen sicher mithilfe Ihrer Verbindungen zusammenstellen.

Migrations

Verwalten Sie das Schema Ihrer Datenbank versioniert.

Seeding

Bringen Sie Entwicklungs- und Testdaten reproduzierbar in Ihre Datenbank.

Architektur

Datenbank

Eloquent

Sicherheit

Ereignisse

E-Mail und Benachrichtigungen

Zahlungen

Asynchrone Verarbeitung

Echtzeitkommunikation

Zeitplanung

Caching und Optimierung

Internationalisierung

Dateien und Speicher

Debugging und Monitoring

Konsole und CLI

Performance

Frontend

KI-Entwicklung

Entwicklungsumgebung

Einführung

Konfiguration

Trennung von Lese- und Schreibverbindung

Veraltete Lesevorgänge auch in Folge-Requests verhindern

Vorübergehend von der Schreibverbindung lesen

Pooled PostgreSQL-Verbindungen

Mehrere Datenbankverbindungen

SQL-Abfragen ausführen

Query Listening

Transaktionen

Nächste Schritte

Query Builder

Migrations

Seeding

​Einführung

​Konfiguration

​Trennung von Lese- und Schreibverbindung

​Veraltete Lesevorgänge auch in Folge-Requests verhindern

​Vorübergehend von der Schreibverbindung lesen

​Pooled PostgreSQL-Verbindungen

​Mehrere Datenbankverbindungen

​SQL-Abfragen ausführen

​Query Listening

​Transaktionen

​Nächste Schritte

Query Builder

Migrations

Seeding

Einführung

Konfiguration

Trennung von Lese- und Schreibverbindung

Veraltete Lesevorgänge auch in Folge-Requests verhindern

Vorübergehend von der Schreibverbindung lesen

Pooled PostgreSQL-Verbindungen

Mehrere Datenbankverbindungen

SQL-Abfragen ausführen

Query Listening

Transaktionen

Nächste Schritte