Von SQLite zu Room migrieren

Die Room-Persistenzbibliothek bietet eine Reihe von Vorteilen gegenüber der direkten Verwendung der SQLite-APIs:

  • Kompilierzeitprüfung von SQL-Abfragen
  • Praktische Annotationen, die sich wiederholenden und fehleranfälligen Boilerplate-Code minimieren
  • Optimierte Datenbankmigrationspfade

Wenn Ihre App eine SQLite-Implementierung ohne Room verwendet, erfahren Sie auf dieser Seite, wie Sie zu Room migrieren. Wenn Room die erste SQLite-Implementierung in Ihrer App ist, finden Sie unter Daten in einer lokalen Datenbank mit Room speichern Informationen zur grundlegenden Verwendung.

Migrationsschritte

Führen Sie die folgenden Schritte aus, um Ihre SQLite-Implementierung zu Room zu migrieren. Wenn Ihre SQLite-Implementierung eine große Datenbank oder komplexe Abfragen verwendet, sollten Sie möglicherweise schrittweise zu Room migrieren. Weitere Informationen zu einer inkrementellen Migrationsstrategie finden Sie unter Inkrementelle Migration.

Abhängigkeiten aktualisieren

Wenn Sie Room in Ihrer App verwenden möchten, müssen Sie die entsprechenden Abhängigkeiten in die Datei build.gradle Ihrer App einfügen. Weitere Informationen zu Room-Abhängigkeiten finden Sie unter Einrichtung.

Modellklassen in Datenentitäten aktualisieren

Room verwendet Datenentitäten, um die Tabellen in der Datenbank darzustellen. Jede Entitätsklasse stellt eine Tabelle dar und hat Eigenschaften, die Spalten in dieser Tabelle darstellen. Führen Sie die folgenden Schritte aus, um Ihre vorhandenen Modellklassen in Room-Entitäten zu aktualisieren:

  1. Kommentieren Sie die Klassendeklaration mit @Entity, um anzugeben, dass es sich um eine Room-Entität handelt. Optional können Sie die tableName Eigenschaft verwenden, um anzugeben, dass die resultierende Tabelle einen anderen Namen als den Klassennamen haben soll.
  2. Kommentieren Sie die Primärschlüsseleigenschaft mit @PrimaryKey.
  3. Wenn eine der Spalten in der resultierenden Tabelle einen anderen Namen als den Namen der entsprechenden Eigenschaft haben soll, kommentieren Sie die Eigenschaft mit @ColumnInfo und legen Sie die name Eigenschaft auf den korrekten Spaltennamen fest.
  4. Wenn die Klasse Eigenschaften hat, die nicht in der Datenbank gespeichert werden sollen, kommentieren Sie diese Eigenschaften mit @Ignore, um anzugeben, dass Room keine Spalten für sie in der entsprechenden Tabelle erstellen soll.
  5. Wenn die Klasse mehr als einen Konstruktor hat, geben Sie an, welchen Konstruktor Room verwenden soll, indem Sie alle anderen Konstruktoren mit @Ignore kommentieren.

@Entity(tableName = "users")
data class User(
    @PrimaryKey @ColumnInfo(name = "userid") val id: String,
    @ColumnInfo(name = "username") val userName: String?,
    @ColumnInfo(name = "last_update") val date: Date?,
)

DAOs erstellen

Room verwendet Data Access Objects (DAOs), um Funktionen zu definieren, die auf die Datenbank zugreifen. Folgen Sie der Anleitung unter Auf Daten mit Room-DAOs zugreifen, um Ihre vorhandenen Abfragefunktionen durch DAOs zu ersetzen.

Datenbankklasse erstellen

Room-Implementierungen verwenden eine Datenbankklasse, um eine Instanz der Datenbank zu verwalten. Ihre Datenbankklasse sollte RoomDatabase erweitern und auf alle von Ihnen definierten Entitäten und DAOs verweisen.

@Database(entities = [User::class], version = 2)
@ColumnTypeConverters(DateConverter::class)
abstract class UsersDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

Migrationspfad definieren

Da sich die Datenbankversionsnummer ändert, müssen Sie ein Migration-Objekt definieren, um die vorhandenen Datenbankdaten beizubehalten. Wenn sich das Datenbankschema nicht ändert, kann diese Migration leer sein.

val MIGRATION_1_2 = object : Migration(1, 2) {
    override suspend fun migrate(connection: SQLiteConnection) {
        // Empty implementation, because the schema isn't changing.
    }
}

Weitere Informationen zu Datenbankmigrationspfaden in Room finden Sie unter Datenbank migrieren.

Datenbankinstanziierung aktualisieren

Nachdem Sie eine Datenbankklasse und einen Migrationspfad definiert haben, können Sie mit Room.databaseBuilder eine Instanz Ihrer Datenbank mit dem Migrationspfad erstellen:

val db =
    Room.databaseBuilder<UsersDatabase>(applicationContext, "database-name")
        .addMigrations(MIGRATION_1_2)
        .build()

Implementierung testen

Testen Sie Ihre neue Room-Implementierung:

  • Folgen Sie der Anleitung unter Migrationen testen, um Ihre Datenbank migration zu testen.
  • Folgen Sie der Anleitung unter Datenbank testen, um Ihre DAO-Funktionen zu testen.

Inkrementelle Migration

Wenn Ihre App eine große, komplexe Datenbank verwendet, ist es möglicherweise nicht möglich, Ihre App auf einmal zu Room zu migrieren. Stattdessen können Sie optional die Datenentitäten und die Room-Datenbank als ersten Schritt implementieren und Ihre Abfragefunktionen später zu DAOs migrieren.

Um eine inkrementelle Migration zu implementieren, rufen Sie mit der Erweiterungsfunktion roomDatabase.getSupportWrapper aus dem Artefakt androidx.room3:room3-sqlite-wrapper einen SupportSQLiteDatabase-Kompatibilitätswrapper ab. Mit diesem Wrapper können Sie direkte SQL-Abfragen im Android-Stil für die von Room verwaltete Datenbank mit Android SQLite-APIs ausführen:

// Get SupportSQLiteDatabase wrapper
val legacyDb = roomDatabase.getSupportWrapper()
legacyDb.execSQL("INSERT INTO users ...")