From 4f64cb105b330f7dfd10a5b7193cf34c505d38dc Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 7 May 2026 16:28:25 +0200
Subject: [PATCH] feat: enhance database migration handling and media asset
 tags

- Updated migration scripts to ensure idempotency and safe execution of SQL statements, preventing errors on repeated runs.
- Improved documentation in migration files to clarify the execution order and idempotent practices for database migrations.
- Added a comment in main.py to explain the migration process and its conditional execution based on the SKIP_DB_MIGRATE environment variable.
---
 backend/main.py                             |  1 +
 backend/migrations/046_media_asset_tags.sql |  4 ++++
 backend/run_migrations.py                   | 13 +++++++++++--
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/backend/main.py b/backend/main.py
index d3a6bfc..28714a7 100644
--- a/backend/main.py
+++ b/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)")
diff --git a/backend/migrations/046_media_asset_tags.sql b/backend/migrations/046_media_asset_tags.sql
index d2211dd..5ece8eb 100644
--- a/backend/migrations/046_media_asset_tags.sql
+++ b/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 '{}';
 
diff --git a/backend/run_migrations.py b/backend/run_migrations.py
index b68d5a5..35f0bbc 100644
--- a/backend/run_migrations.py
+++ b/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_`).