Esegui la migrazione da SQLite a stanza virtuale

La libreria di persistenza Room offre una serie di vantaggi rispetto all'utilizzo diretto delle API SQLite:

  • Verifica in fase di compilazione delle query SQL
  • Annotazioni pratiche che riducono al minimo il codice boilerplate ripetitivo e soggetto a errori
  • Percorsi di migrazione del database semplificati

Se la tua app ha un'implementazione SQLite non Room, leggi questa pagina per scoprire come eseguire la migrazione a Room. Se Room è la prima implementazione SQLite nella tua app, consulta Salvare i dati in un database locale utilizzando Room per l'utilizzo di base.

Passi per la migrazione

Segui questi passaggi per eseguire la migrazione dell'implementazione SQLite a Room. Se l'implementazione SQLite utilizza un database di grandi dimensioni o query complesse, potresti preferire eseguire la migrazione a Room gradualmente. Per saperne di più su una strategia di migrazione incrementale, consulta Migrazione incrementale.

Aggiorna le dipendenze

Per utilizzare Room nella tua app, devi includere le dipendenze appropriate nel file build.gradle dell'app. Per saperne di più sulle dipendenze di Room, consulta Configurazione.

Aggiorna le classi modello alle entità dati

Room utilizza le entità dati per rappresentare le tabelle nel database. Ogni classe di entità rappresenta una tabella e ha proprietà che rappresentano le colonne di quella tabella. Segui questi passaggi per aggiornare le classi modello esistenti in modo che diventino entità Room:

  1. Annota la dichiarazione della classe con @Entity per indicare che si tratta di un' entità Room. Facoltativamente, puoi utilizzare la tableName proprietà per indicare che la tabella risultante deve avere un nome diverso da il nome della classe.
  2. Annota la proprietà della chiave primaria con @PrimaryKey.
  3. Se una delle colonne della tabella risultante deve avere un nome diverso da quello della proprietà corrispondente, annota la proprietà con @ColumnInfo e imposta la proprietà name sul nome della colonna corretto.
  4. Se la classe ha proprietà di cui non vuoi mantenere la persistenza nel database, annotale con @Ignore per indicare che Room non deve creare colonne per queste nella tabella corrispondente.
  5. Se la classe ha più di un costruttore, indica quale costruttore deve utilizzare Room annotando tutti gli altri costruttori con @Ignore.

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

Crea DAO

Room utilizza gli oggetti di accesso ai dati (DAO) per definire le funzioni che accedono al database. Segui le indicazioni riportate in Accedere ai dati utilizzando i DAO di Room per sostituire le funzioni di query esistenti con i DAO.

Crea una classe di database

Le implementazioni di Room utilizzano una classe di database per gestire un'istanza del database. La classe di database deve estendere RoomDatabase e fare riferimento a tutte le entità e i DAO che hai definito.

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

Definisci un percorso di migrazione

Poiché il numero di versione del database sta cambiando, devi definire un Migration oggetto per conservare i dati del database esistenti. Se lo schema del database non cambia, questa migrazione può essere vuota.

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

Per saperne di più sui percorsi di migrazione del database in Room, consulta Eseguire la migrazione del database.

Aggiorna l'istanza del database

Dopo aver definito una classe di database e un percorso di migrazione, puoi utilizzare Room.databaseBuilder per creare un'istanza del database con il percorso di migrazione applicato:

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

Verifica la tua implementazione

Assicurati di testare la nuova implementazione di Room:

Migrazione incrementale

Se la tua app utilizza un database di grandi dimensioni e complesso, potrebbe non essere fattibile eseguire la migrazione dell'app a Room in una sola volta. In alternativa, puoi implementare facoltativamente le entità dati e il database Room come primo passaggio e poi eseguire la migrazione delle funzioni di query nei DAO in un secondo momento.

Per implementare una migrazione incrementale, ottieni un wrapper di compatibilità SupportSQLiteDatabase utilizzando la funzione di estensione roomDatabase.getSupportWrapper dall'artefatto androidx.room3:room3-sqlite-wrapper. Questo wrapper ti consente di eseguire query SQL dirette in stile Android sul database gestito da Room utilizzando le API SQLite di Android:

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