bollwerk/docs/migration-guide.md

Room-Migrationen – Entwickler-Leitfaden

Grundsatz

Ab Version 6 nutzt die App Room @AutoMigration für Schema-Änderungen. Room generiert die Migrationen automatisch – User müssen nichts tun.

fallbackToDestructiveMigration() ist als Fallback aktiv: Kann Room keine automatische Migration ableiten, wird die DB zurückgesetzt und neu erstellt.

Aktuelle DB-Version

Version 6 (Stand: Mai 2026)

Historische manuelle Migrationen (v1–v5) wurden entfernt. Keine Rückwärtskompatibilität zu älteren DB-Versionen.

Checkliste für neue Schema-Änderungen

1. DB-Version hochzählen: version in BollwerkDatabase anpassen
2. @AutoMigration ergänzen: autoMigrations = [AutoMigration(from = X, to = Y)] in der @Database-Annotation
3. Falls AutoMigration nicht reicht (z.B. Column-Rename, Table-Rebuild):
   • @RenameColumn / @DeleteColumn AutoMigrationSpec schreiben
   • Oder manuelle Migration(X, Y) in Migrations.kt + DatabaseModule.addMigrations()
4. Schema-Export prüfen: JSON in app/schemas/ wird automatisch generiert

Beispiel: Einfache Spalte hinzufügen

// BollwerkDatabase.kt
@Database(
    entities = [...],
    version = 7,
    autoMigrations = [AutoMigration(from = 6, to = 7)],
    exportSchema = true
)

Fertig – Room erkennt die neue Spalte automatisch.

Beispiel: Spalte umbenennen

@Database(
    entities = [...],
    version = 7,
    autoMigrations = [AutoMigration(from = 6, to = 7, spec = V6ToV7::class)],
    exportSchema = true
)
abstract class BollwerkDatabase : RoomDatabase() {
    @RenameColumn(tableName = "items", fromColumnName = "old_name", toColumnName = "new_name")
    class V6ToV7 : AutoMigrationSpec
}

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