Kairo-Jinkendo/docs/MIGRATIONS.md

Migrationen & Data-Seeds

Kairo trennt Schema-Migrationen (einmalig) von Data-Seeds (idempotent, bei Änderung erneut ausführbar).

Schema-Migrationen

Pfad	backend/migrations/NNN_beschreibung.sql
Tracking	Tabelle schema_migrations
Ausführung	Beim Backend-Start (run_migrations.py), überspringbar via SKIP_DB_MIGRATE=1
Regel	Jede Datei wird genau einmal angewendet. Änderungen → neue nummerierte Datei.

Data-Seeds

Pfad	backend/seeds/seed_NNN_beschreibung.sql oder .py
Tracking	Tabelle data_seeds (Name + SHA256-Checksum)
Ausführung	Nach Schema-Migrationen (run_seeds.py), überspringbar via SKIP_SEEDS=1
Regel	Seed läuft erneut, wenn die Datei geändert wurde (Checksum abweicht) oder --force gesetzt ist.

Umgebungsfilter

Dateien mit .dev. im Namen (z. B. seed_001_…​.dev.sql) laufen nicht in Production (ENVIRONMENT=production).

Seeds manuell ausführen

docker compose -f docker-compose.dev-env.yml exec backend python run_seeds.py
docker compose -f docker-compose.dev-env.yml exec backend python run_seeds.py --only seed_001_cleanup_pytest_artifacts --force

Aktuelle Seeds

Seed	Typ	Zweck
seed_001_cleanup_pytest_artifacts	SQL (dev)	Entfernt pytest/CI-User (*@example.com) und verwaiste Test-Tenants
seed_002_bootstrap_admin	Python	Legt Systemadmin aus KAIRO_BOOTSTRAP_* an, wenn noch kein User existiert
seed_003_ensure_dev_admin	Python (dev)	Entfernt fremde Dev-User, stellt lars@stommer.com als Portal-Admin sicher (jeder Start)

Dev-Seeds (.dev.*) werden in Nicht-Prod-Umgebungen bei jedem Backend-Start erneut ausgeführt.

Neuen Seed anlegen

1. Datei backend/seeds/seed_NNN_kurzname.sql oder .py anlegen (Python: def run() -> None:).
2. SQL idempotent halten (DELETE … WHERE …, INSERT … ON CONFLICT, etc.).
3. Nur Dev/CI: .dev.sql / .dev.py Suffix verwenden.
4. Nach Deploy prüfen: python run_seeds.py — bei geänderter Datei wird der Seed automatisch erneut ausgeführt.

Tests & CI

• pytest setzt SKIP_SEEDS=1 beim App-Import; Cleanup läuft über Fixture + nach CI-pytest.
• Geteilte Dev-DB wird nach jedem Test-Lauf bereinigt (run_seeds.py --only seed_001_cleanup_pytest_artifacts --force).