AutoMigration

public abstract @interface AutoMigration
implements Annotation

androidx.room.AutoMigration


Declares an automatic migration on a Database.

An automatic migration is a Migration that is generated via the use of database schema files at two versions of a RoomDatabase. Room automatically detects changes on the database between these two schemas, and constructs a Migration to migrate between the two versions. In case of ambiguous scenarios (e.g. column/table rename/deletes), additional information is required, and can be provided via the AutoMigrationSpec property.

An auto migration must define the 'from' and 'to' versions of the schema for which a migration implementation will be generated. A class that implements AutoMigrationSpec can be declared in the AutoMigrationSpec property to either provide more information for ambiguous scenarios or execute callbacks during the migration.

If there are any column/table renames/deletes between the two versions of the database provided then it is said that there are ambiguous scenarios in the migration. In such scenarios then an AutoMigrationSpec is required and the class provided must be annotated with the relevant change annotation(s): RenameColumn, RenameTable, DeleteColumn or DeleteTable. When no ambiguous scenario is present, then the AutoMigrationSpec property is optional.

If an auto migration is defined for a database, then Database.exportSchema() must be set to true.

Example:

 @Database(
      version = MusicDatabase.LATEST_VERSION,
      entities = {
          Song.class,
          Artist.class
      },
      autoMigrations = {
          @AutoMigration (
              from = 1,
              to = 2
          ),
         @AutoMigration (
              from = 2,
              to = 3,
              spec = MusicDatabase.MyExampleAutoMigration.class
          )
      },
      exportSchema = true
 )
 public abstract class MusicDatabase extends RoomDatabase {
     static final int LATEST_VERSION = 3;

    @DeleteTable(deletedTableName = "Album")
    @RenameTable(fromTableName = "Singer", toTableName = "Artist")
    @RenameColumn(
          tableName = "Song",
          fromColumnName = "songName",
          toColumnName = "songTitle"
     )
    @DeleteColumn(fromTableName = "Song", deletedColumnName = "genre")
     static class MyExampleAutoMigration implements AutoMigrationSpec {
         @Override
          default void onPostMigrate(@NonNull SupportSQLiteDatabase db) {
              // Invoked once auto migration is done
          }
     }
 }
 

Summary

Public methods

int from()

Version of the database schema to migrate from.

Class<?> spec()

User implemented custom auto migration spec.

int to()

Version of the database schema to migrate to.

Inherited methods

Public methods

from

public int from ()

Version of the database schema to migrate from.

Returns
int Version number of the database to migrate from.

spec

public Class<?> spec ()

User implemented custom auto migration spec.

Returns
Class<?> The auto migration specification or none if the user has not implemented a spec

to

public int to ()

Version of the database schema to migrate to.

Returns
int Version number of the database to migrate to.