La libreria di persistenza Room offre una serie di vantaggi rispetto all'uso diretto delle API SQLite:
- Verifica in fase di compilazione delle query SQL
- Annotazioni utili che riducono al minimo i codici boilerplate ripetitivi e soggetti a errori
- Percorsi di migrazione dei database semplificati
Se al momento la tua app utilizza un'implementazione non Room di SQLite, leggi questa pagina per scoprire come eseguire la migrazione della tua app per utilizzare invece Room. Se Room è la prima implementazione SQLite che utilizzi nella tua app, consulta Salvare dati in un database locale utilizzando Room per informazioni di base sull'utilizzo.
Passaggi per la migrazione
Esegui i passaggi seguenti per eseguire la migrazione dell'implementazione SQLite alla stanza virtuale. Se l'implementazione SQLite utilizza un database di grandi dimensioni o query complesse, potresti preferire la migrazione graduale alla stanza virtuale. Consulta Migrazione incrementale per una strategia di migrazione incrementale.
Aggiorna dipendenze
Per utilizzare Room nella tua app, devi includere le dipendenze appropriate nel
file build.gradle
dell'app. Consulta Configurazione per
le dipendenze delle stanze più aggiornate.
Aggiorna le classi del modello in entità di dati
La stanza virtuale utilizza le entità di dati per rappresentare le tabelle nel database. Ogni classe di entità rappresenta una tabella e contiene campi che rappresentano le colonne. Segui questi passaggi per aggiornare le classi di modello esistenti in modo che siano entità Room:
- Annota la dichiarazione della classe con
@Entity
per indicare che si tratta di un'entità Room. Facoltativamente, puoi utilizzare la proprietàtableName
per indicare che la tabella risultante deve avere un nome diverso da quello della classe. - Annota il campo della chiave primaria con
@PrimaryKey
. - Se una delle colonne nella tabella risultante deve avere un nome diverso da quello del campo corrispondente, annota il campo con
@ColumnInfo
e imposta la proprietàname
sul nome della colonna corretto. - Se la classe contiene campi che non vuoi mantenere nel database, annotali con
@Ignore
per indicare che Room non deve creare colonne per questi campi nella tabella corrispondente. - Se la classe ha più di un metodo del costruttore, indica quale costruttore deve utilizzare la stanza annotando tutti gli altri costruttori con
@Ignore
.
Kotlin
@Entity(tableName = "users") data class User( @PrimaryKey @ColumnInfo(name = "userid") val mId: String, @ColumnInfo(name = "username") val mUserName: String?, @ColumnInfo(name = "last_update") val mDate: Date?, )
Java
@Entity(tableName = "users") public class User { @PrimaryKey @ColumnInfo(name = "userid") private String mId; @ColumnInfo(name = "username") private String mUserName; @ColumnInfo(name = "last_update") private Date mDate; @Ignore public User(String userName) { mId = UUID.randomUUID().toString(); mUserName = userName; mDate = new Date(System.currentTimeMillis()); } public User(String id, String userName, Date date) { this.mId = id; this.mUserName = userName; this.mDate = date; } }
Crea DAO
La stanza virtuale utilizza gli oggetti di accesso ai dati (DAO) per definire i metodi che accedono al database. Segui le indicazioni in Accesso ai dati utilizzando i DAO delle stanze per sostituire i metodi di query esistenti con i DAO.
Crea una classe di database
Le implementazioni della camera utilizzano una classe di database per gestire un'istanza del database. La classe del database deve estendere RoomDatabase
e fare riferimento a tutte le entità e DAO che hai definito.
Kotlin
@Database(entities = [User::class], version = 2) @TypeConverters(DateConverter::class) abstract class UsersDatabase : RoomDatabase() { abstract fun userDao(): UserDao }
Java
@Database(entities = {User.class}, version = 2) @TypeConverters(DateConverter.class) public abstract class UsersDatabase extends RoomDatabase { public abstract UserDao userDao(); }
Definisci un percorso di migrazione
Poiché il numero di versione del database sta cambiando, devi definire un oggetto Migration
per indicare un percorso di migrazione in modo che Room mantenga i dati esistenti nel database.
Finché lo schema del database non cambia, potrebbe trattarsi di un'implementazione vuota.
Kotlin
val MIGRATION_1_2 = object : Migration(1, 2) { override fun migrate(database: SupportSQLiteDatabase) { // Empty implementation, because the schema isn't changing. } }
Java
static final Migration MIGRATION_1_2 = new Migration(1, 2) { @Override public void migrate(SupportSQLiteDatabase database) { // Empty implementation, because the schema isn't changing. } };
Per scoprire di più sui percorsi di migrazione del database nella stanza virtuale, consulta Eseguire la migrazione del database.
Aggiorna l'istanza del database
Dopo aver definito una classe del database e un percorso di migrazione, puoi utilizzare Room.databaseBuilder
per creare un'istanza del database con il percorso di migrazione applicato:
Kotlin
val db = Room.databaseBuilder( applicationContext, AppDatabase::class.java, "database-name" ) .addMigrations(MIGRATION_1_2).build()
Java
db = Room.databaseBuilder( context.getApplicationContext(), UsersDatabase.class, "database-name" ) .addMigrations(MIGRATION_1_2).build();
Testare l'implementazione
Assicurati di testare la nuova implementazione delle stanze virtuali:
- Segui le indicazioni in Testare le migrazioni per testare la migrazione del database.
- Segui le indicazioni riportate nella sezione Testare il database per testare i metodi DAO.
Migrazione incrementale
Se la tua app utilizza un database complesso e di grandi dimensioni, potrebbe non essere possibile eseguire la migrazione dell'app alla stanza virtuale contemporaneamente. Facoltativamente, puoi implementare le entità dei dati e il database delle camere come primo passaggio, quindi eseguire la migrazione dei metodi di query in DAO in un secondo momento. Puoi farlo sostituendo la tua classe helper database personalizzata con l'oggetto SupportSQLiteOpenHelper
che ricevi da RoomDatabase.getOpenHelper()
.
Risorse aggiuntive
Per scoprire di più sulla migrazione da SQLite a Room, consulta le seguenti risorse aggiuntive:
Blog
- 7 passi per arrivare alla stanza virtuale
- Esegui la migrazione incrementale da SQLite alla stanza virtuale