# 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")
}
```