---
title: "Migrationen"
description: "Nummerierte SQL-Migrationen, die durch den Nibiru CLI getrieben werden."
---

Migrationen sind flache SQL-Dateien im Verzeichnis `application/settings/config/database/`, die in numerischer Reihenfolge ausgeführt werden. Die Befehlszeilenschnittstelle verfolgt, welche Dateien ausgeführt wurden, und überspringt sie bei nachfolgenden Aufrufen.

## Dateinamenskonventionen
```
NNN-<slug>.sql
```
- `NNN`: Null aufgefüllte dreistellige Nummer für die Sortierreihenfolge.
- `<slug>`: Bindestrich-getrennte Beschreibung (`add-account-email`, `create-acl-data`).

Beispiel-Aufschlüsselung:
```
001-acl.sql
002-account.sql
003-api_registry.sql
004-timeanddate.sql
005-user.sql
006-user_to_account.sql
007-timeanddate_to_account.sql
008-user_to_acl.sql
009-account_to_api_registry.sql
010-timeanddate_to_user.sql
011-acl-data.sql
012-add-unique-key-user.sql
013-add-account-email.sql
```
## Migrations ausführen
```bash
./nibiru -mi local                              # APPLICATION_ENV=development
APPLICATION_ENV=staging   ./nibiru -mi staging
APPLICATION_ENV=production ./nibiru -mi production
```
Der `{env}`-Argument und die `APPLICATION_ENV` sollten übereinstimmen. Migrationen zielen auf die in `settings.<env>.ini` unter `[DATABASE]` konfigurierte Datenbank ab.

## Was der Runner macht

Für jede `*.sql`-Datei in numerischer Reihenfolge:

1. Sucht nach seinem Dateinamen in der Tabelle `_migrations`.
2. Wenn nicht vorhanden, öffnet eine Transaktion (wenn der Treiber DDL-Transaktionen unterstützt), führt die Datei aus und fügt einen Datensatz bei Erfolg ein.
3. Wenn eine Anweisung fehlschlägt, wird rückgängig gemacht und mit einem Nicht-null-Ausgang beendet.

Die `_migrations` Tabelle wird beim ersten Start automatisch erstellt.

## Idempotente SQL

Schreiben Sie immer Migrationen, die ohne Fehler erneut ausgeführt werden können, nach einem teilweisen Fehler:
```sql
CREATE TABLE IF NOT EXISTS api_registry (
    api_registry_id    INT(11) NOT NULL AUTO_INCREMENT,
    api_registry_name  VARCHAR(255) NOT NULL,
    PRIMARY KEY (api_registry_id),
    UNIQUE KEY api_registry_name_uk (api_registry_name)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;
```
Für PostgreSQL:
```sql
CREATE TABLE IF NOT EXISTS api_registry (
    api_registry_id    SERIAL PRIMARY KEY,
    api_registry_name  TEXT NOT NULL UNIQUE
);
```
Für ALTER-Anweisungen bevorzugen Sie Klauseln mit `IF NOT EXISTS` auf unterstützten Engines:
```sql
ALTER TABLE "user" ADD COLUMN IF NOT EXISTS user_email VARCHAR(255);
```
Falls Ihr Motor keine Unterstützung für `IF NOT EXISTS` bei der Änderung bietet, umschließen Sie die Anweisung in eine Guard-Abfrage, die nichts tut, wenn die Änderung bereits vorhanden ist.

## Befehle zum Zurücksetzen

::: caution
Die Reset-Befehle leeren die Migrations-Audit-Tabelle – sie löschen Ihre Datenbanktabellen nicht. Nach einem Reset führt der nächste `-mi` *jede* Migration erneut aus. Stellen Sie sicher, dass Ihr SQL idempotent ist, bevor Sie zurücksetzen.
:::
```bash
./nibiru -mi-reset local                       # forget all applied migrations
./nibiru -mi-reset-file 005-user.sql local     # forget a single file
```
Das Einzeldateiformular ist nützlich, wenn Sie einen Fehler in einer zuvor angewandten Migration behoben haben und nur diese Datei erneut ausführen möchten.

## Verzweigungsreinheit

Zwei Ingenieure, die an parallelen Zweigen arbeiten, können beide `015-…` hinzufügen und kollidieren. Konventionen, die helfen:

- **Zahlen in Pull-Request-Titeln vorbehalten**, bevor Sie die SQL schreiben.
- **Verwenden Sie einen großen Abstand** für Hotfixes (z.B. behalten Sie `099`, `199`, `299` für Notfall-Picks vor).
- **Fügen Sie lieber additive Migrationen** (neue Tabellen, neue Spalten) als zerstörende ones (Drops) hinzu. Diese führen sauberer zusammen.

## Zusammenführen

Für langfristige Projekte sollten alte Migrationen regelmäßig in eine einzelne Seed-Datei zusammengefasst werden, die das *aktuelle* Schema darstellt. Verschieben Sie die Originalien nach `archive/`, sodass der Überwachungsverlauf weiterhin besteht, und erstellen Sie eine neue `000-baseline-2026.sql`, die alles auf einmal erstellt. Aktualisieren Sie den Migrationsrunner mit einer manuellen `INSERT INTO _migrations`, um alte Dateien als angewendet zu markieren.

## Schema-first Modelle

Wenn `[GENERATOR] database = true` ist, werden die Modelle nach jeder Migration aus dem Live-Schema neu generiert. Also ist ein typischer Deploy-Workflow:
```bash
./nibiru -mi production
# Generator regenerates models on the next request.
./nibiru -cache-clear
```
Für zero-downtime Deploys: Deaktivieren Sie den Generator (`database = false`) und übertragen Sie die neu generierten Modelle zusammen mit den Migrationen, auf denen sie abhängen.
