When Do We Migrate?

On our RoomDatabase subclass, we have a @Database annotation. One of the properties is version. This works like the version code that we would pass into the SQLiteOpenHelper constructor. It is a monotonically increasing integer, with higher numbers indicating newer schemas. The version in the code represents the schema version that this code is expecting.

Once your app ships, any time you change your schema — mostly in the form of modifying entity classes — you need to increment that version and create a Migration that knows how to convert from the prior version to this new one.

Note that there is no requirement that you increment the version by 1, though that is a common convention. If using a date-based format like YYYMMDD (e.g., 20170627) makes your life easier, you are welcome to do so.