Easily move your tables between rooms

Implementing database migrations with Room just became easier, with the help of auto-migrations, introduced in version 2.4.0-alpha01. Until now, whenever your database schema changes you had to implement a Migration class and tell Room what exactly had changed. In most cases, this involved writing and executing complex SQL queries.

Now with the auto-migration feature, you indicate from which version to which version you want to migrate. Room can automatically generate migrations for simple cases like column addition, removal or new tables. For more ambiguous scenarios, Room will need some help. You’ll be able to provide concrete specifications — like a column or a table renamed or deleted — based on this, Room will generate and run the migration for you. Let’s check out some examples and see how this looks!

Putting the auto in auto-migrations

Let’s say that we’re adding a new column to a table, going from version 1 to version 2 of our database. We’ll have to update the @Database annotation by incrementing the version number and adding an auto-migration from version 1 to 2:

Whenever your database version changes again, just update the list of auto-migrations adding the new one:

For entities declared in @Database schema changes like adding a new column or table, updating the primary key, foreign key or indices or changing the default value of a column and more are automatically detected by Room and don’t require any other input.

⚠️Note: Under the hood, Room auto-migrations rely on the generated database schema, so make sure that the exportSchema option in @Database is true while using autoMigrations. Otherwise it leads to an error: Cannot create auto-migrations when export schema is OFF.

When auto-migrations need a little help

Room auto-migrations can’t detect all the possible changes performed on the database, so sometimes they need some help. A common example is that Room can’t detect whether a table or a column was renamed or deleted. When this happens, Room will throw a compile time error asking you to implement a AutoMigrationSpec. This class allows you to specify the type of change you made. Implement an AutoMigrationSpec and annotate it with one or more of:

• @DeleteTable(tableName)
• @RenameTable(fromTableName, toTableName)
• @DeleteColumn(tableName, columnName)
• @RenameColumn(tableName, fromColumnName, toColumnName)

For example, let’s say that we’re renaming the Doggos table to GoodDoggos. Room can’t detect whether this is a completely new table and we deleted the Doggos table, or the table was renamed and all of the values need to be kept.

Migrations vs Auto-migrations

When to use Migrations

To manually handle migrations, Room has offered the Migration class since version 1.0. Whenever you have complex database schema changes to make, you’ll have to use this class. For example, let’s say that we’ve decided to split a table into 2 different tables. Room can’t detect how this split has been performed, and can’t automatically detect which data to move. So this is when you’ll have to implement a Migration class and add it to the databaseBuilder() via addMigrations() method:

Combining migrations and auto-migrations

Room allows combining migrations with auto-migrations. For example, migrating from version 1 to version 2 may be done using Migration, version 2 to version 3 using auto-migration etc. If you define a Migration and an auto-migration for the same version, then the Migration will be run.

Under the hood an auto-migration constructs a Migration class, so the same migration logic described in detail here still applies. TL;DR: When the database is first accessed, Room checks whether the current database version is different from the one in @Database. If yes, Room looks for migration paths going from one to the other. Migrations are then run consecutively.

Testing auto-migrations

To test auto-migrations, you can use the MigrationTestHelper test rule and call helper.runMigrationsAndValidate(), in the same way as when using the Migration class. Read more about testing migrations in our documentation.

Conclusion

The auto-migration feature allows you to easily handle database schema changes by using the autoMigration parameter in @Database. While a lot of the basic cases can be handled by Room, for table / column delete or rename you’ll have to implement a AutoMigrationSpec. For all other cases, continue using Migrations.

This feature is currently in alpha. Help us make it better by providing feedback on our issue tracker.