Migrationen

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

./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:

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:

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:

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. :::

./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:

./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.