Room database migration

Preface

Be careful ： This article is advanced Room Part of a series , This series covers Room All details of the persistence Library .

Database migration is a very important concept in any application development . When we add and change functions in your application , We must update the database architecture . Whenever the architecture of any of our tables changes , If we don't want our users to lose all existing data , We need to write migrations for existing applications .

for example , We can consider a table called users, It contains user information , It has 3 Columns uid, Namely first_name and last_name. Now? , If we Add a new column age, We need to write a migration to change the current table schema —— namely , Add a name The new column of age.

Room The persistence library allows us to write classes in this way Migration To save user data . Every Migration Class specifies a startVersion and endVersion. At run time ,Room Run each Migration Class migrate() Method , Migrate the database to a later version in the correct order .

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("ALTER TABLE users ADD COLUMN age INTEGER")
    }
}

Now we have created the migration object MIGRATION_1_2, We need to use the database builder to add it to the database configuration .

Room.databaseBuilder(
    applicationContext, 
    UserDatabase::class.java, 
    "users-db"
).addMigrations(MIGRATION_1_2)
.build()

Gracefully handle missing migration paths

After updating the schema of our database , Databases on some devices may still use older schema versions . If Room Cannot find the migration rule to upgrade the database of the device from the old version to the current version , It throws out one IllegalStateException The error that caused our application to crash .

To prevent the application from crashing when this happens , please fallbackToDestructiveMigration() Call... When creating the database builder Method .

Room.databaseBuilder(
    applicationContext, 
    UserDatabase::class.java, 
    "users-db"
).fallbackToDestructiveMigration()
.build()

Destructive entertainment fallback logic includes several additional options ：

• If there is an error in the schema history of a specific version that cannot be solved through the migration path , Please use fallbackToDestructiveMigrationFrom(). This method indicates that you want Room Use fallback logic only if the database attempts to migrate from one of these problematic versions .
• To perform destructive reconstruction only when attempting mode degradation , please fallbackToDestructiveMigrationOnDowngrade() change to the use of sth. .

This is the use of Room How to complete the migration .