bollwerkadmin/bollwerk
1
0
Fork 0
Code Issues 9 Pull requests Projects Releases Packages Wiki Activity Actions
bollwerk/Anforderungen/design/db-migration/candidates.md
Jens Reinemann 1df2d1cff5 refactor: manuelle DB-Migrationen durch Room AutoMigration ersetzen 
- DB-Version auf 6 hochgezaehlt (Clean-Slate, keine Rueckwaertskompatibilitaet)
- Alle manuellen Migrationen (v1-v5) aus Migrations.kt entfernt
- DatabaseModule: addMigrations() durch fallbackToDestructiveMigration() ersetzt
- migration-guide.md: AutoMigration-Workflow dokumentiert
- Instrumentierte Tests: alte Migrationstests durch frische DB-Tests ersetzt
- Schema 6.json exportiert

Closes #89
2026-05-17 11:43:27 +02:00

4.3 KiB
Raw Blame History

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.