90580ecb3e
Migrations.kt: KDoc für MIGRATION_2_3 und MIGRATION_3_4 ergänzt. KrisenvorratDatabaseMigrationTest: MIGRATION_3_4 in alle Testhelfer aufgenommen, createV3Database() + openMigratedDbV4() hinzugefügt, Tests für v3→v4 (messages-Tabelle) und v1→v4 Full-Path-Migration ergänzt. freshInstall-Test registriert jetzt alle Migrationen. docs/migration-guide.md: Entwickler-Leitfaden mit Checkliste, SQLite-Einschränkungen und Testanleitung. fallbackToDestructiveMigration() war bereits entfernt; dieses Ticket stellt sicher, dass alle Migrationspfade getestet und dokumentiert sind. Closes #71
78 lines
2.5 KiB
Markdown
78 lines
2.5 KiB
Markdown
# Room-Migrationen – Entwickler-Leitfaden
|
||
|
||
## Grundsatz
|
||
|
||
**`fallbackToDestructiveMigration()` ist verboten.** Jede Schema-Änderung muss durch eine
|
||
explizite Migration abgedeckt sein, damit User-Daten bei App-Updates erhalten bleiben.
|
||
|
||
## Aktuelle DB-Version
|
||
|
||
**Version 4** (Stand: Mai 2026)
|
||
|
||
| Migration | Änderung |
|
||
|-----------|----------|
|
||
| v1 → v2 | `kcal_per_100g` → `kcal_per_kg`, `min_stock` entfernt |
|
||
| v2 → v3 | Tabelle `pending_sync_ops` hinzugefügt |
|
||
| v3 → v4 | Tabelle `messages` hinzugefügt |
|
||
|
||
## Checkliste für neue Schema-Änderungen
|
||
|
||
1. **Migration schreiben**: Neues `Migration(X, Y)`-Objekt in `Migrations.kt` ergänzen
|
||
2. **DB-Version hochzählen**: `version` in `KrisenvorratDatabase` anpassen
|
||
3. **Migration registrieren**: In `DatabaseModule.addMigrations()` eintragen
|
||
4. **Test schreiben**: Migrationspfad in `KrisenvorratDatabaseMigrationTest` testen
|
||
5. **Pflichtfelder**: Bei neuen Pflichtfeldern ohne sinnvollen Default → interaktiven MigrationScreen ergänzen
|
||
|
||
## Migration schreiben
|
||
|
||
```kotlin
|
||
// In Migrations.kt
|
||
val MIGRATION_4_5 = object : Migration(4, 5) {
|
||
override fun migrate(db: SupportSQLiteDatabase) {
|
||
// SQL-Statements für die Schema-Änderung
|
||
db.execSQL("ALTER TABLE items ADD COLUMN new_column TEXT NOT NULL DEFAULT ''")
|
||
}
|
||
}
|
||
```
|
||
|
||
### Wichtige SQLite-Einschränkungen
|
||
|
||
- **ALTER TABLE RENAME COLUMN** erst ab SQLite 3.25 (Android API 29). Bei minSdk < 29:
|
||
Tabelle neu erstellen, Daten kopieren, alte Tabelle löschen, neue umbenennen.
|
||
- **ALTER TABLE DROP COLUMN** erst ab SQLite 3.35 (Android API 34). Gleiche Workaround-Strategie.
|
||
- **Immer `CREATE TABLE IF NOT EXISTS`** für neue Tabellen verwenden.
|
||
- **Indizes** nach Table-Rebuild neu erstellen (`CREATE INDEX IF NOT EXISTS`).
|
||
|
||
## Tests schreiben
|
||
|
||
Jede Migration braucht mindestens:
|
||
|
||
1. **Schema-Test**: Prüfen, dass neue Spalten/Tabellen existieren und alte entfernt sind
|
||
2. **Daten-Test**: Prüfen, dass bestehende Daten nach der Migration erhalten sind
|
||
3. **Full-Path-Test**: Prüfen, dass v1 → aktuelle Version ohne Fehler durchläuft
|
||
|
||
```kotlin
|
||
@Test
|
||
fun migrate4To5_newColumnExists() {
|
||
createV4Database()
|
||
val db = openMigratedDbV5()
|
||
try {
|
||
// Schema prüfen
|
||
// Daten prüfen
|
||
} finally {
|
||
db.close()
|
||
}
|
||
}
|
||
```
|
||
|
||
## Schema-Export
|
||
|
||
Room exportiert Schemas automatisch nach `app/schemas/`. Diese JSON-Dateien werden
|
||
versioniert und können für `MigrationTestHelper` verwendet werden.
|
||
|
||
Konfiguration in `app/build.gradle.kts`:
|
||
```kotlin
|
||
ksp {
|
||
arg("room.schemaLocation", "$projectDir/schemas")
|
||
}
|
||
```
|