Jens Reinemann 90580ecb3e refactor(room): fallbackToDestructiveMigration entfernen und Migrationstests vervollständigen

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

2026-05-17 02:40:20 +02:00

2.5 KiB

Raw Blame History

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

Migration schreiben: Neues Migration(X, Y)-Objekt in Migrations.kt ergänzen
DB-Version hochzählen: version in KrisenvorratDatabase anpassen
Migration registrieren: In DatabaseModule.addMigrations() eintragen
Test schreiben: Migrationspfad in KrisenvorratDatabaseMigrationTest testen
Pflichtfelder: Bei neuen Pflichtfeldern ohne sinnvollen Default → interaktiven MigrationScreen ergänzen

Migration schreiben

// 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:

Schema-Test: Prüfen, dass neue Spalten/Tabellen existieren und alte entfernt sind
Daten-Test: Prüfen, dass bestehende Daten nach der Migration erhalten sind
Full-Path-Test: Prüfen, dass v1 → aktuelle Version ohne Fehler durchläuft

@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:

ksp {
    arg("room.schemaLocation", "$projectDir/schemas")
}

2.5 KiB Raw Blame History Unescape Escape