Migracja z SQLite do pokoju

Biblioteka trwałości danych Room zapewnia szereg korzyści w porównaniu z bezpośrednim używaniem interfejsów API SQLite:

  • Weryfikacja zapytań SQL w czasie kompilowania.
  • Adnotacje ułatwiające pracę, które minimalizują podatny na błędy powtarzalny kod.
  • Uproszczone ścieżki migracji bazy danych.

Jeśli Twoja aplikacja ma implementację SQLite inną niż Room, przeczytaj tę stronę, aby dowiedzieć się, jak przeprowadzić migrację do Room. Jeśli Room jest pierwszą implementacją SQLite w Twojej aplikacji, podstawowe informacje o korzystaniu z niej znajdziesz w artykule Zapisywanie danych w lokalnej bazie danych za pomocą biblioteki Room.

Kroki migracji

Aby przenieść implementację SQLite do Room, wykonaj te czynności. Jeśli Twoja implementacja SQLite korzysta z dużej bazy danych lub złożonych zapytań, możesz stopniowo migrować do Room. Więcej informacji o strategii migracji przyrostowej znajdziesz w artykule Migracja przyrostowa.

Uaktualnianie zależności

Aby używać Room w aplikacji, musisz dodać odpowiednie zależności w pliku build.gradle aplikacji. Więcej informacji o zależnościach Room znajdziesz w artykule Konfiguracja.

Aktualizowanie klas modeli do encji danych

Room używa encji danych do reprezentowania tabel w bazie danych. Każda klasa encji reprezentuje tabelę i ma właściwości, które reprezentują kolumny w tej tabeli. Aby zaktualizować istniejące klasy modeli do encji Room, wykonaj te czynności:

  1. Dodaj adnotację @Entity do deklaracji klasy, aby wskazać, że jest to encja Room. Opcjonalnie możesz użyć właściwości tableName, aby wskazać, że wynikowa tabela powinna mieć nazwę inną niż nazwa klasy.
  2. Dodaj adnotację @PrimaryKey do właściwości klucza podstawowego.
  3. Jeśli któraś z kolumn w wynikowej tabeli ma mieć nazwę inną niż nazwa odpowiadającej jej właściwości, dodaj do tej właściwości adnotację @ColumnInfo i ustaw właściwość name na prawidłową nazwę kolumny.
  4. Jeśli klasa ma właściwości, których nie chcesz utrwalać w bazie danych, dodaj do nich adnotację @Ignore, aby wskazać, że Room nie powinien tworzyć dla nich kolumn w odpowiedniej tabeli.
  5. Jeśli klasa ma więcej niż 1 konstruktor, wskaż, którego konstruktora Room ma używać, dodając adnotację @Ignore do wszystkich pozostałych konstruktorów.

@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?,
)

Tworzenie obiektów DAO

Room używa obiektów dostępu do danych (DAO) do definiowania funkcji, które uzyskują dostęp do bazy danych. Aby zastąpić istniejące funkcje zapytań obiektami DAO, postępuj zgodnie ze wskazówkami w artykule Uzyskiwanie dostępu do danych za pomocą obiektów DAO w bibliotece Room.

Tworzenie klasy bazy danych

Implementacje Room używają klasy bazy danych do zarządzania instancją bazy danych. Klasa bazy danych powinna rozszerzać RoomDatabase i odwoływać się do wszystkich zdefiniowanych encji i obiektów DAO.

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

Definiowanie ścieżki migracji

Ponieważ numer wersji bazy danych się zmienia, musisz zdefiniować obiekt Migration, aby zachować istniejące dane bazy danych. Jeśli schemat bazy danych się nie zmienia, ta migracja może być pusta.

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

Więcej informacji o ścieżkach migracji bazy danych w Room znajdziesz w artykule Migracja bazy danych.

Aktualizowanie tworzenia instancji bazy danych

Po zdefiniowaniu klasy bazy danych i ścieżki migracji możesz użyć Room.databaseBuilder, aby utworzyć instancję bazy danych z zastosowaną ścieżą migracji:

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

Testowanie implementacji

Pamiętaj, aby przetestować nową implementację Room:

  • Aby przetestować migrację bazy danych, postępuj zgodnie ze wskazówkami w artykule Testowanie migracji.
  • Aby przetestować funkcje DAO, postępuj zgodnie ze wskazówkami w artykule Testowanie bazy danych.

Migracja przyrostowa

Jeśli Twoja aplikacja korzysta z dużej, złożonej bazy danych, migracja aplikacji do Room może być niemożliwa. Zamiast tego możesz opcjonalnie zaimplementować encje danych i bazę danych Room jako pierwszy krok, a następnie przenieść funkcje zapytań do obiektów DAO.

Aby zaimplementować migrację przyrostową, uzyskaj otokę zgodności SupportSQLiteDatabase za pomocą funkcji rozszerzenia roomDatabase.getSupportWrapper z artefaktu androidx.room3:room3-sqlite-wrapper. Ta otoka umożliwia wykonywanie bezpośrednich zapytań SQL w stylu Androida w bazie danych zarządzanej przez Room za pomocą interfejsów API SQLite Androida:

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