backend/main.py

@@ -33,6 +33,7 @@ def _health_ready_public_detail_enabled() -> bool:
 
 
 # Run database migrations before API start — halbes Schema ist schlimmer als kein Start
+# (run_migrations: pending *.sql in einer Transaktion pro Datei, Buchführung schema_migrations)
 # Lokal ohne DB / nur Tests: SKIP_DB_MIGRATE=1
 if os.getenv("SKIP_DB_MIGRATE", "").strip().lower() in ("1", "true", "yes"):
     print("[SKIP_DB_MIGRATE] Migrationen uebersprungen (nur fuer Entwicklung ohne DB)")

backend/migrations/046_media_asset_tags.sql

@@ -1,4 +1,8 @@
 -- Migration 046: Schlagwörter (tags) für media_assets — Suche & Filter in der Medienbibliothek.
+--
+-- Einordnung: läuft nach 045 (media_assets existiert). Idempotent:
+--   • wird pro Umgebung höchstens einmal über schema_migrations ausgeführt;
+--   • dieselben Statements sind bei Wiederholung harmlos (IF NOT EXISTS).
 ALTER TABLE media_assets
   ADD COLUMN IF NOT EXISTS tags TEXT[] NOT NULL DEFAULT '{}';
 

backend/run_migrations.py

@@ -2,8 +2,17 @@
 """
 Shinkan Jinkendo — Datenbank-Migrationen
 
-**Idempotent** über `schema_migrations`: jede numerische Datei `migrations/*.sql` höchstens einmal
-als „erfolgreich“ eingetragen; bei erneutem Start werden nur noch fehlende Dateien abgearbeitet.
+**Deployment:** Beim Start importiert `main.py` dieses Modul und ruft `main()` auf, bevor FastAPI
+die App lädt (`SKIP_DB_MIGRATE=1` nur für Tests oder ohne DB). Jeder Backend-Container-Start
+wendet ausstehende Migrationen an — kein separater Deploy-Schritt nötig.
+
+**Idempotent (Runner):** Über `schema_migrations` wird jede Datei `NNN_*.sql` höchstens einmal
+als erfolgreich markiert; wiederholte Starts führen nur noch fehlende Dateien aus.
+
+**Idempotent (SQL, empfohlen):** `IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`,
+damit ein erneuter Lauf derselben Datei harmlos bleibt. Ohne diese Guards schützt nur der
+`schema_migrations`-Eintrag; ältere Migrationen ohne IF NOT EXISTS können bei manuell gelöschtem
+Eintrag und bestehenden Tabellen fehlschlagen.
 
 **Reihenfolge:** Alle `NNN_*.sql` nach führender Zahl (001 vor 009 vor 010 …), bei gleicher Zahl
 alphabetisch nach Dateinamen — nicht bloß String-Sortierung (vermeidet z. B. `10_` vor `9_`).