Поддерживает ли Room автоматические миграции

Поддержка автоматических миграций в Room

Да, библиотека Room, начиная с версии 2.4.0-alpha01 (и стабильно с 2.4.0), поддерживает автоматические миграции (Auto Migrations) для определенных сценариев изменения схемы базы данных. Это значительное улучшение, которое уменьшает объем ручного кода и снижает риск ошибок при управлении миграциями. Однако важно понимать, что автоматические миграции покрывают не все случаи, и их поддержка имеет четкие ограничения.

Что такое автоматическая миграция в Room?

Автоматическая миграция позволяет Room самостоятельно генерировать и выполнять SQL-скрипты для миграции базы данных от одной версии схемы к другой, без необходимости разработчику явно писать код в классе Migration. Room анализирует различия между двумя версиями схемы (например, между @Database(version = 1) и @Database(version = 2)) и создает необходимые SQL-команды.

Типы изменений, поддерживаемые автоматическими миграциями

Автоматические миграции поддерживают следующие безопасные (non-destructive) изменения схемы:

• Добавление новых таблиц (@Entity).
• Удаление существующих таблиц.
• Добавление новых колонок в существующую таблицу.
• Удаление существующих колонок из таблицы.
• Создание новых индексов.
• Удаление существующих индексов.

Как использовать автоматические миграции

Чтобы объявить автоматическую миграцию, вам необходимо:

1. Увеличить версию базы данных в аннотации @Database.
2. Добавить объект AutoMigration в параметр autoMigrations аннотации @Database, указав начальную (from) и конечную (to) версии.

Пример объявления:

@Database(
    version = 2,
    entities = [User::class, Post::class],
    autoMigrations = [
        AutoMigration(from = 1, to = 2)
    ]
)
abstract class AppDatabase : RoomDatabase() {
    // ...
}

Если изменение схемы включает удаление колонки или таблицы, Room требует предоставить специальную аннотацию @DeleteColumn или @DeleteTable на соответствующем классе Entity старой версии (или создать специальный класс-спеку), чтобы явно указать, что было удалено. Это необходимо, потому Room не может отследить удаленные элементы из текущего кода.

Пример с удалением колонки:

// Старая версия Entity (v1) предположительно имела колонку 'age'
@Entity
data class UserV1(
    @PrimaryKey val id: Int,
    val name: String,
    val age: Int // Колонка, которая будет удалена в версии 2
)

// В версии 2 (или в отдельном спеке) указываем удаление
@Database(
    version = 2,
    entities = [User::class], // User в версии 2 уже без 'age'
    autoMigrations = [
        AutoMigration(from = 1, to = 2, spec = AppDatabase.MyAutoMigration::class)
    ]
)
abstract class AppDatabase : RoomDatabase() {
    // Специальный класс, указывающий удаленные элементы
    @DeleteColumn(tableName = "User", columnName = "age")
    class MyAutoMigration
}

Ограничения и важные замечания

• Не поддерживаются сложные изменения: Автоматические миграции НЕ поддерживают изменение типа или имени существующей колонки, добавление ограничений (CONSTRAINTS) или другие комплексные трансформации данных. Для таких операций вам все еще необходимо использовать классический ручной Migration с явным SQL.

// Пример ручной миграции для изменения типа колонки
val MIGRATION_1_2 = Migration(1, 2) {
    it.execSQL("ALTER TABLE User ALTER COLUMN age TYPE INTEGER")
}

• Тестирование критически важно: Автоматически генерируемый SQL следует всегда проверять и тестировать на реальных устройствах. Room выводит логи миграции, которые можно анализировать.
• Инструменты анализа схемы: Для получения подробной информации о различиях между версиями можно использовать средства схема Room (Room Schema) или плагин Database Inspector в Android Studio.
• Резервное копирование данных: При удалении таблиц или колонок данные будут потеряны. Автоматическая миграция не выполняет резервное копирование или трансформацию данных.

Рекомендации по использованию

1. Для простых добавлений/удалений таблиц или колонок — используйте автоматические миграции. Это безопасно и эффективно.
2. Для любых изменений, затрагивающих существующие данные (изменение типа, преобразование значений, сложные ограничения) — всегда пишите ручные миграции.
3. Сочетайте подходы: В одном увеличении версии базы данных можно использовать как автоматические миграции для простых изменений, так и ручные для сложных.
4. Версионирование схемы: Храните файлы схемы Room (JSON) для каждой версии базы данных. Это помогает в отладке и является хорошей практикой.

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