Datenbankkonfiguration

Erläutert die Konfiguration von Datenbankverbindungen in Laravel, Read/Write-Splitting, mehrere Verbindungen, SQL-Ausführung, Query Listening und die Grundlagen von Transaktionen.

​

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.

​

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

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.