Datenbank-Migrationen

Was sind Migrationen

Migrationen sind gewissermaßen Versionskontrolle für die Datenbank. Sie erlauben es einem Team, Definitionen des Datenbankschemas gemeinsam zu pflegen. Sie kennen bestimmt die Situation, in der Sie nach einem Pull der Sourcen Kollegen bitten müssen, eine Spalte manuell in ihrer Datenbank zu ergänzen. Migrationen lösen genau dieses Problem. Migrationsdateien liegen im Verzeichnis database/migrations. Der Dateiname enthält einen Zeitstempel, über den Laravel die Reihenfolge der Ausführung bestimmt.

Migration erzeugen

Erzeugen Sie eine neue Migrationsdatei mit make:migration.

php artisan make:migration create_posts_table

Aus dem Migrationsnamen leitet Laravel den Tabellennamen ab und legt einen passenden Stub an. Bei create_posts_table wird bereits Code zum Anlegen der Tabelle posts erzeugt.

Aufbau einer Migration

Eine Migrationsklasse hat zwei Methoden: up und down.

up: Fügt Tabellen, Spalten oder Indexe hinzu.
down: Kehrt up um. Wird beim Rollback aufgerufen.

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Migration ausführen
     */
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->text('body');
            $table->boolean('published')->default(false);
            $table->timestamps();
        });
    }

    /**
     * Migration zurücksetzen
     */
    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

Wichtige Spaltenmethoden

Die Klasse Blueprint bietet zahlreiche Spaltentypen.

Methode	Beschreibung
`$table->id()`	Auto-Increment-Primärschlüssel (Alias von `bigIncrements('id')`)
`$table->string('name')`	VARCHAR (Default 255 Zeichen)
`$table->text('body')`	TEXT
`$table->integer('count')`	INTEGER
`$table->boolean('active')`	TINYINT als Boolean
`$table->timestamp('published_at')`	TIMESTAMP
`$table->timestamps()`	`created_at` und `updated_at` gemeinsam
`$table->softDeletes()`	Spalte `deleted_at` für Soft Deletes
`$table->foreignId('user_id')`	`BIGINT UNSIGNED` für Fremdschlüssel

Spaltenmodifikatoren

Über Method-Chaining fügen Sie Modifikatoren hinzu.

$table->string('email')->unique();
$table->string('name')->nullable();
$table->integer('votes')->default(0);
$table->string('title')->after('id'); // hinter der angegebenen Spalte einfügen

Vektorspalten und -indizes

Die Methode vector erstellt eine vector-Spalte zum Speichern von Embedding-Vektoren. Setze dimensions auf die Ausgabedimension des von dir verwendeten Embedding-Anbieters.

$table->vector('embedding', dimensions: 1536);

Vektorspalten sind auf PostgreSQL-Verbindungen mit der pgvector-Erweiterung sowie auf MariaDB 11.7 oder neuer verfügbar. Aktiviere unter PostgreSQL pgvector, bevor du eine Vektorspalte anlegst.

Schema::ensureVectorExtensionExists();

Um Ähnlichkeitssuchen über Vektoren zu beschleunigen, füge der vector-Spalte einen index hinzu. Dieser Index verwendet die Kosinus-Distanz.

$table->vector('embedding', dimensions: 1536)->index();

Um einen bestehenden Vektorindex zu entfernen, nutze dropVectorIndex.

$table->dropVectorIndex('documents_embedding_vectorindex');

Online-Indexerstellung

Wenn du einen Index auf einer großen Tabelle erstellst, wird die Tabelle in der Regel während des Aufbaus des Index gesperrt und Lese- und Schreibzugriffe müssen warten. In MySQL kannst du das Modifikator inplace an eine Index- oder Fremdschlüssel-Definition anhängen, um die Operation mit dem INPLACE-Algorithmus auszuführen.

Schema::table('users', function (Blueprint $table) {
    $table->index('email')->inplace();
    $table->foreign('team_id')
        ->references('id')
        ->on('teams')
        ->inplace();
});

Kombiniere inplace mit dem Modifikator lock, um die Tabellensperre während der Operation zu steuern. Mit none bleiben Lese- und Schreibzugriffe für Operationen möglich, die MySQL zulässt.

Schema::table('users', function (Blueprint $table) {
    $table->index('email')->inplace()->lock('none');
});

Dieses Feature ist MySQL-spezifisch. Prüfe in der MySQL-Dokumentation zu Online-DDL-Operationen, ob die Operation, die du ausführst, den INPLACE-Algorithmus und den angegebenen Lock-Modus unterstützt. Wenn du inplace für Fremdschlüssel-Operationen verwendest, deaktiviere zuvor die Fremdschlüssel-Constraints.

Migrationen ausführen

Führen Sie alle ausstehenden Migrationen mit migrate aus.

php artisan migrate

Den Status prüfen Sie mit migrate:status.

php artisan migrate:status

In Produktion erscheint bei migrate eine Bestätigungsabfrage. Zur unbeaufsichtigten Ausführung nutzen Sie --force, achten Sie aber auf potenziellen Datenverlust.

Rollback

Setzen Sie die letzte Migrations-Batch mit migrate:rollback zurück.

php artisan migrate:rollback

Mit --step beschränken Sie den Rollback auf eine bestimmte Anzahl.

# Die letzten 5 Migrationen zurücksetzen
php artisan migrate:rollback --step=5

Um alles zurückzusetzen und erneut auszuführen, nutzen Sie migrate:refresh.

php artisan migrate:refresh

migrate:refresh legt alle Tabellen neu an – bestehende Daten gehen verloren. Praktisch zum Zurücksetzen der Entwicklungs-DB.

Beispiel: `posts`-Tabelle anlegen

Kompletter Ablauf am Beispiel einer Blog-Post-Tabelle.

1. Migration erzeugen

php artisan make:migration create_posts_table

2. Migration bearbeiten

Öffnen Sie database/migrations/xxxx_xx_xx_xxxxxx_create_posts_table.php und passen Sie den Inhalt an.

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('title');
            $table->text('body');
            $table->boolean('published')->default(false);
            $table->timestamp('published_at')->nullable();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

3. Migration ausführen

php artisan migrate

Die Tabelle posts wird angelegt.

4. Nachträglich Spalten hinzufügen

Um später weitere Spalten zu ergänzen, erstellen Sie eine neue Migration, statt bestehende zu ändern.

php artisan make:migration add_excerpt_to_posts_table

public function up(): void
{
    Schema::table('posts', function (Blueprint $table) {
        $table->string('excerpt')->nullable()->after('title');
    });
}

public function down(): void
{
    Schema::table('posts', function (Blueprint $table) {
        $table->dropColumn('excerpt');
    });
}

Bearbeiten Sie bestehende Migrationen möglichst nicht direkt. Es entstehen Inkonsistenzen zu Kollegen und Produktion. Änderungen werden immer als neue Migrationen hinzugefügt.

Migrations-Events

Bei jedem Migrationsschritt werden Events gefeuert. Alle erben von Illuminate\Database\Events\MigrationEvent.

Klasse	Beschreibung
`Illuminate\Database\Events\DatabaseRefreshed`	Nach `migrate:refresh`
`Illuminate\Database\Events\MigrationsStarted`	Vor einer Migrations-Batch
`Illuminate\Database\Events\MigrationsEnded`	Nach einer Migrations-Batch
`Illuminate\Database\Events\MigrationStarted`	Vor einer einzelnen Migration
`Illuminate\Database\Events\MigrationEnded`	Nach einer einzelnen Migration
`Illuminate\Database\Events\NoPendingMigrations`	Wenn keine offene Migration vorliegt
`Illuminate\Database\Events\SchemaDumped`	Nach dem Schema-Dump
`Illuminate\Database\Events\SchemaLoaded`	Nach Laden eines Schema-Dumps

Beispiel: nach Abschluss der Migrationen den Cache leeren.

use Illuminate\Database\Events\MigrationsEnded;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Event;

Event::listen(MigrationsEnded::class, function () {
    Cache::flush();
});

Erste Schritte

Grundlagen

Request-Verarbeitung

Datenbank

Authentifizierung

Helfer und externe Kommunikation

Tests und Deployment

KI-Entwicklungsunterstützung

Was sind Migrationen

Migration erzeugen

Aufbau einer Migration

Wichtige Spaltenmethoden

Spaltenmodifikatoren

Vektorspalten und -indizes

Online-Indexerstellung

Migrationen ausführen

Rollback

Beispiel: `posts`-Tabelle anlegen

1. Migration erzeugen

2. Migration bearbeiten

3. Migration ausführen

4. Nachträglich Spalten hinzufügen

Migrations-Events

Nächste Schritte

Datenbank-Seeding

Einstieg in Eloquent

​Was sind Migrationen

​Migration erzeugen

​Aufbau einer Migration

​Wichtige Spaltenmethoden

​Spaltenmodifikatoren

​Vektorspalten und -indizes

​Online-Indexerstellung

​Migrationen ausführen

​Rollback

​Beispiel: posts-Tabelle anlegen

​1. Migration erzeugen

​2. Migration bearbeiten

​3. Migration ausführen

​4. Nachträglich Spalten hinzufügen

​Migrations-Events

​Nächste Schritte

Datenbank-Seeding

Einstieg in Eloquent

Was sind Migrationen

Migration erzeugen

Aufbau einer Migration

Wichtige Spaltenmethoden

Spaltenmodifikatoren

Vektorspalten und -indizes

Online-Indexerstellung

Migrationen ausführen

Rollback

Beispiel: `posts`-Tabelle anlegen

1. Migration erzeugen

2. Migration bearbeiten

3. Migration ausführen

4. Nachträglich Spalten hinzufügen

Migrations-Events

Nächste Schritte