# Technology Candidates – DB-Migrationsstrategie

Date: 2026-05-17
Requirements file: requirements.md

## Candidate Table

| Name | Beschreibung | Anwendung | Room-Version | Adoption | Req. Coverage | Score |
| ---- | ------------ | --------- | ------------ | -------- | ------------- | ----- |
| A – Manuelle Migrations | Handgeschriebene `Migration(X, Y)` mit SQL | Jede Schema-Änderung | 1.0+ | Widespread | Alle Must-Haves ✅ | 7 |
| B – Auto-Migration | Room generiert SQL aus `@AutoMigration` | Einfache Änderungen | 2.4+ | Moderate | Alle Must-Haves ✅, limitiert bei Renames/Drops | 5 |
| C – Hybrid | Auto-Migration + manuelle Migration für Komplexes | Alle Fälle | 2.4+ | Moderate | Alle Must-Haves ✅, alle Should-Haves ✅ | 8 |

## Candidate Details

### A – Manuelle Room-Migrations

**Beschreibung:** Für jede Schema-Änderung wird ein `Migration(X, Y)`-Objekt in `Migrations.kt` geschrieben, das die SQL-Statements direkt enthält.

**Requirement coverage:**

- ✅ Must: Datenerhaltung, Room 2.6.1, testbar, rückwärtskompatibel, minSdk 26
- ✅ Should: Compile-time Validierung (Room prüft Schema), Checkliste vorhanden
- ⚠️ Missing: Kein reduzierter Boilerplate für einfache Fälle (ADD COLUMN braucht gleich viel Code wie Table-Rebuild)

**Stärken:**
- Volle Kontrolle über jeden SQL-Statement
- Kein "Magie"-Faktor – alles explizit und reviewbar
- Bewährt im Projekt (4 Migrationen funktionieren fehlerfrei)
- Funktioniert mit jeder SQLite-Version

**Schwächen:**
- Boilerplate: Selbst ein simples `ADD COLUMN` braucht ~15 Zeilen Code
- Fehleranfällig: SQL-Typos werden erst zur Laufzeit entdeckt
- Table-Rebuild-Pattern für Renames/Drops ist aufwändig und repetitiv

**Risiken:** Gering. Ist der Status quo, bewährt, keine neuen Abhängigkeiten.

---

### B – Auto-Migration (Room 2.4+)

**Beschreibung:** Room generiert Migrations-SQL automatisch aus dem Schema-Diff zwischen zwei `@Database`-Versionen. Konfiguriert über `@AutoMigration(from = X, to = Y)` direkt an der Database-Klasse.

**Requirement coverage:**

- ✅ Must: Datenerhaltung, Room 2.6.1, testbar, rückwärtskompatibel
- ⚠️ Must: minSdk 26 – Auto-Migration generiert intern Table-Rebuilds, aber **Renames und Deletes erfordern `@AutoMigration.Spec`** mit `@RenameColumn`/`@DeleteColumn` Annotationen
- ✅ Should: Minimaler Boilerplate für einfache Fälle
- ⚠️ Should: Eingeschränkt bei komplexen Fällen (Daten-Transformation, bedingte Migrationen)

**Stärken:**
- Null Boilerplate für einfache Fälle (ADD COLUMN, neue Tabelle)
- Compile-time Fehler wenn Schema-Diff nicht auflösbar
- Room generiert korrekten SQL für die jeweilige SQLite-Version

**Schwächen:**
- **Kann nicht alle Fälle abdecken:** Daten-Transformationen (z.B. Werte umrechnen), bedingte Logik, oder komplexe Multi-Tabellen-Migrationen sind unmöglich
- **Rückblick auf bestehende Migrationen:** 2 von 4 bestehenden Migrationen (V1→V2: Rename + Delete + Daten kopieren, V4→V5: Table-Rebuild) hätten Auto-Migration allein nicht bewältigt
- Auto-Migration als **alleinige** Strategie wäre für dieses Projekt unzureichend

**Risiken:** Hoch als Allein-Strategie. Mindestens 50% der bisherigen Migrationen wären nicht abbildbar gewesen.

---

### C – Hybrid (Auto-Migration + Manuelle Fallbacks)

**Beschreibung:** Auto-Migration als Default für einfache Schema-Änderungen (ADD COLUMN, neue Tabellen). Manuelle Migration für alles Komplexe (Renames, Deletes, Daten-Transformationen). Klare Entscheidungsregeln, wann welcher Ansatz.

**Requirement coverage:**

- ✅ Must: Alle erfüllt
- ✅ Should: Reduzierter Boilerplate für einfache Fälle, Compile-time Validierung, klare Checkliste
- ✅ Nice: Automatische Schema-Diff-Generierung für einfache Fälle

**Stärken:**
- Best of both worlds: Wenig Code für einfache Fälle, volle Kontrolle für komplexe
- Bestehende manuelle Migrationen bleiben unverändert
- Klare Entscheidungsmatrix: "Ist es nur ADD COLUMN / neue Tabelle? → Auto. Sonst → Manuell."
- Room 2.6.1 unterstützt beides parallel

**Schwächen:**
- Leicht erhöhte kognitive Komplexität: Entwickler müssen wissen, wann welcher Ansatz
- Zwei Patterns im gleichen Projekt (aber mit klaren Regeln beherrschbar)

**Risiken:** Gering. Die Entscheidungsregel ist einfach und die `migration-guide.md` dokumentiert sie.