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

# Datenbank-Migrationen

> Erfahren Sie, wie Sie mit den Migrations-Funktionen von Laravel Ihre Datenbank-Schemata versionieren.

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

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

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

## Migrationen ausführen

Führen Sie alle ausstehenden Migrationen mit `migrate` aus.

```shell theme={null}
php artisan migrate
```

Den Status prüfen Sie mit `migrate:status`.

```shell theme={null}
php artisan migrate:status
```

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

## Rollback

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

```shell theme={null}
php artisan migrate:rollback
```

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

```shell theme={null}
# Die letzten 5 Migrationen zurücksetzen
php artisan migrate:rollback --step=5
```

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

```shell theme={null}
php artisan migrate:refresh
```

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

## Beispiel: `posts`-Tabelle anlegen

Kompletter Ablauf am Beispiel einer Blog-Post-Tabelle.

### 1. Migration erzeugen

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

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

```shell theme={null}
php artisan make:migration add_excerpt_to_posts_table
```

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

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

## Migrations-Events

Bei jedem Migrationsschritt werden [Events](/de/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.

```php theme={null}
use Illuminate\Database\Events\MigrationsEnded;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Event;

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

## Nächste Schritte

<Card title="Datenbank-Seeding" icon="seedling" href="/de/seeding">
  Legen Sie Beispieldaten in Ihren Tabellen an.
</Card>

<Card title="Einstieg in Eloquent" icon="database" href="/de/eloquent">
  Arbeiten Sie mit Ihren Tabellen über das Eloquent ORM.
</Card>


## Related topics

- [Verzeichnisstruktur](/de/directory-structure.md)
- [Datenbank-Seeding](/de/seeding.md)
- [Datenbanktests](/de/database-testing.md)
- [Einführung in Eloquent](/de/eloquent.md)
- [Laravel-Pakete mit Orchestra Testbench testen](/de/advanced/package-testing.md)