До сегодняшнего дня любые изменения структуры базы данных надо было прописывать вручную в классе Migration, сообщая Room, что именно изменилось. В большинстве случаев это влекло за собой написание сложных SQL-запросов.

Начиная с версии 2.4.0-alpha01, миграция структуры базы данных в Room существенно упростилась — появились автоматические миграции (auto-migration).

В простых случаях (например, добавление или удаление столбца, создание новой таблицы) вы лишь указываете, из какой версии в какую вы хотите мигрировать, а Room ~~сделает всю грязную работу за вас~~ автоматически сгенерирует миграции.

В более сложных (и неоднозначных) случаях Room'у потребуется помощь: вам нужно будет указать, какой столбец или таблица была переименована или удалена. На основании этих данных Room автоматически сгенерирует и запустит миграцию.

Давайте рассмотрим несколько примеров, чтобы лучше понять, как это работает.

Включаем автоматические миграции

Предположим, мы добавляем новый столбец в таблицу (переходим от версии 1 к версии 2). В результате мы должны будем обновить аннотацию @Database, увеличив номер версии и прописав конкретные версии в AutoMigration:

И каждый раз, когда версия вашей базы данных будет меняться, просто обновляйте список автоматических миграций, добавляя новый элемент AutoMigration:

В каких случаях Room справится сам? Когда сможет разобраться, что поменялось в схеме БД. Для него не составит труда выявить:

добавление нового столбца,
обновление первичного ключа, внешнего ключа или индекса,
изменение значения по умолчанию и т.д.

Важно: автоматические миграции полагаются на сгенерированную схему базы данных. Если собираетесь использовать автоматические миграции, убедитесь, что значение параметра exportSchema равно true. Иначе получите ошибку: Cannot create auto-migrations when export schema is OFF.

Когда потребуется ручное вмешательство?

Повторюсь, иногда Room'у требуется помощь. Он не в силах обнаружить все возможные варианты изменений, вносимых в базу данных.

Типичный пример: Room не сможет достоверно определить, была ли таблица (или столбец) переименована или удалена. А когда это выяснится, Room выбросит ошибку компиляции и попросит реализовать AutoMigrationSpec, который описывает внесённые изменения.

При реализации интерфейса AutoMigrationSpec используйте следующие аннотации:

@DeleteTable(tableName) — имя таблицы, которую мы удалили,
@RenameTable(fromTableName, toTableName) — старое и новое имя таблицы, которую мы переименовали,
@DeleteColumn(tableName, columnName) — имя столбца, который мы удалили,
@RenameColumn(tableName, fromColumnName, toColumnName) — старое и новое имя столбца, который мы переименовали, с указанием конкретной таблицы.

Предположим, мы решили переименовать таблицу Doggos в GoodDoggos. Room не может определить:

или GoodGoggos , действительно, новая таблица, а старую таблицу (Doggos) мы удалили,
или же старая таблица Doggos была переименована, и всю содержащуюся в ней информацию нужно сохранить.

Поэтому пропишем все изменения вручную:

Обычные миграции vs. автоматические миграции

Когда стоит использовать миграции

Начиная с версии 1.0, Room содержит в себе класс Migration для ручной обработки миграций. Когда вам необходимо внести сложные изменения в схему базы данных, используйте этот класс.

Предположим, мы решили разбить одну таблицу на две. Room не может определить, как было выполнено это разделение. Соответственно, он не может автоматически определить, какие данные нужно переместить.

В этом случае необходимо реализовать класс Migration, добавив в него databaseBuilder() с помощью метода addMigrations():

Комбинируем обычные и автоматические миграции

Room позволяет комбинировать обычные и автоматические миграции. Например, миграция между версиями 1 и 2 может быть выполнена с помощью Migration, а переход с 2 на 3 — с помощью автоматической миграции и т.д.

Если переход между одними и теми же версиями будет объявлен и с помощью обычной миграции, и с помощью автоматической миграции, сработает обычная миграция.

Как это работает?

Автоматические миграции работают так: сначала создаётся обычный класс Migration, логика его работы известна и описана здесь.

Если вкратце, при первом обращении к базе данных Room проверяет, отличается ли текущая версия от той, что есть в @Database. Если отличается, Room ищет соответствующие миграции и последовательно их запускает.

Тестирование автоматических миграций

Для тестирования автоматических миграций используйте MigrationTestHelper и вызывайте helper.runMigrationsAndValidate() так же, как при использовании класса Migration.

Подробнее о тестировании миграций читайте в документации.

Заключение

Автоматические миграции позволяют обрабатывать простые изменения схемы базы данных. Включение этой функции не составляет труда — добавьте параметр autoMigrations в аннотацию @Database (не забудьте про exportSchema = true).

Простые случаи Room может обрабатывать автоматически, но в более сложных и неоднозначных ситуациях нам необходимо описать суть внесённых изменений. Во всех остальных случаях используйте обычные миграции.

Функционал автоматических миграций находится в статусе альфа. Помогите нам сделать его лучше, оставив отзыв в баг-трекере.

Полезные ссылки

Документация по @AutoMigration.
Список коммитов, которые вошли в версию 2.4.0-alpha01.

Автоматические миграции в Room