AutoMigration

Added in 2.4.0

Kotlin |Java

@Target(allowedTargets = [AnnotationTarget.CLASS])
@Retention(value = AnnotationRetention.BINARY)
public annotation AutoMigration

Declares an automatic migration on a Database.

An automatic migration is a androidx.room.migration.Migration that is generated via the use of database schema files at two versions of a androidx.room.RoomDatabase. Room automatically detects changes on the database between these two schemas, and constructs a androidx.room.migration.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 androidx.room.migration.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 androidx.room.migration.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 androidx.room.migration.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 androidx.room.migration.AutoMigrationSpec property is optional.

If an auto migration is defined for a database, then androidx.room.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
)
abstract class MusicDatabase  : RoomDatabase() {
   const val LATEST_VERSION = 3

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

See also
`RoomDatabase`
`AutoMigrationSpec`

Summary

Public constructors
`AutoMigration(int from, int to, @NonNull KClass<@NonNull ?> spec)`

Public methods
`final int`	`getFrom()` Version of the database schema to migrate from.
`final @NonNull KClass<@NonNull ?>`	`getSpec()` User implemented custom auto migration spec.
`final int`	`getTo()` Version of the database schema to migrate to.

Public constructors

AutoMigration

public AutoMigration(int from, int to, @NonNull KClass<@NonNull ?> spec)

Public methods

getFrom

public final int getFrom()

Version of the database schema to migrate from.

Returns
`int`	Version number of the database to migrate from.

getSpec

public final @NonNull KClass<@NonNull ?> getSpec()

User implemented custom auto migration spec.

Returns
`@NonNull KClass<@NonNull ?>`	The auto migration specification or none if the user has not implemented a spec

getTo

public final int getTo()

Version of the database schema to migrate to.

Returns
`int`	Version number of the database to migrate to.