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.

Aktuelle Schema-Migrationen

Nr.	Datei	AP	Inhalt
001	001_init_core.sql	AP0.1	kairo_app_meta
002	002_auth_identity_tenant_actor.sql	AP0.2	User, Tenant, Actor, Session, audit_log
003	003_data_seeds_tracking.sql	AP0.2+	data_seeds
004	004_capabilities_registry.sql	AP0.3	capabilities, role_capability_grants
005	005_prompt_feature_config_registry.sql	AP0.4	Feature/Prompt/Placeholder/Config
006	006_initiatives_actions.sql	AP0.5	initiatives, actions, action_assignments

Aktuelle Schema-Version: 006 (backend/version.py → DB_SCHEMA_VERSION).

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), verwaiste Test-Tenants; löscht zuerst Initiatives (AP0.5 FK)
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).