Migraciones: cambiar el esquema sin perder datos

Una migración es la única operación de tu app que se ejecuta sobre datos que no controlas, en un dispositivo que no ves, y que si falla no admite reintento: los datos ya no están. Todo lo demás en Room se puede corregir con una actualización; una migración destructiva mal desplegada es irreversible para el usuario que la sufrió. Por eso este es el nivel donde la disciplina importa más que la técnica, y donde el esquema exportado en JSON deja de ser un artefacto burocrático para convertirse en la única fuente de verdad de lo que hay realmente en el disco de un teléfono ajeno.

El hash de identidad: por qué Room se niega a abrir

Cada vez que compilas, Room calcula un hash a partir de la descripción completa del esquema —tablas, columnas, tipos, restricciones, índices— y lo incrusta en el código generado. Al abrir la base compara ese hash con el que la propia base guarda en su tabla interna de metadatos, y si el número de versión coincide pero el hash no, lanza una excepción en lugar de operar: prefiere que la app falle al arrancar en tu emulador a ejecutar consultas contra un esquema que no es el que el código cree. La causa habitual es haber cambiado una entidad sin subir la versión.

@Database(
    entities = [Nota::class, Etiqueta::class],
    version = 3,
    exportSchema = true,
)
abstract class AppDatabase : RoomDatabase()

El fichero JSON que exportSchema deposita en el directorio de esquemas contiene ese hash y la descripción canónica de cada versión. Debe entrar en el control de versiones. Sin el JSON de la versión anterior no hay forma fiable de saber qué había en el disco de los usuarios, ni Room puede generar migraciones automáticas, ni el test de migración tiene contra qué comparar.

Migraciones automáticas y dónde se detienen

Room puede generar la migración él mismo comparando dos JSON consecutivos, siempre que el cambio sea inequívoco.

@Database(
    entities = [Nota::class],
    version = 2,
    autoMigrations = [AutoMigration(from = 1, to = 2)],
    exportSchema = true,
)
abstract class AppDatabase : RoomDatabase()

Añadir una tabla o una columna con valor por defecto es inequívoco: solo hay una traducción posible a SQL. Renombrar, en cambio, es ambiguo: al comparar dos esquemas, una columna renombrada es indistinguible de una borrada más otra creada, y esas interpretaciones difieren en si los datos sobreviven. Ante esa ambigüedad, Room exige que la resuelvas tú con una especificación.

@RenameColumn(tableName = "notas", fromColumnName = "cuerpo", toColumnName = "contenido")
@DeleteColumn(tableName = "notas", columnName = "obsoleta")
class MigracionUnoADos : AutoMigrationSpec

// y en la anotación:
// autoMigrations = [AutoMigration(from = 1, to = 2, spec = MigracionUnoADos::class)]

Migración manual: el patrón de recreación de tabla

Cuando el cambio transforma datos, la migración se escribe a mano. Room te entrega la base abierta dentro de una transacción y tú ejecutas SQL.

val MIGRACION_2_3 = object : Migration(2, 3) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE notas ADD COLUMN prioridad INTEGER NOT NULL DEFAULT 0")
        db.execSQL("UPDATE notas SET prioridad = 1 WHERE archivada = 0")
    }
}

El límite de SQLite es su soporte parcial de ALTER TABLE: puede añadir columnas y renombrar, pero no cambiar el tipo de una columna ni alterar restricciones. Para eso existe el patrón canónico de cuatro pasos, que hay que ejecutar en este orden exacto.

flowchart TD
A[Version antigua en el disco] --> B[Crear tabla nueva con el esquema destino]
B --> C[Copiar datos con INSERT SELECT y transformarlos]
C --> D[Borrar la tabla antigua]
D --> E[Renombrar la nueva al nombre original]
E --> F[Recrear indices y disparadores]
F --> G{Room valida el esquema resultante}
G -->|Coincide con el JSON| H[Apertura correcta]
G -->|No coincide| I[Excepcion de migracion invalida]
style H fill:#a6e3a1,color:#11111b
style I fill:#f38ba8,color:#11111b

val MIGRACION_3_4 = object : Migration(3, 4) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("""
            CREATE TABLE notas_nueva (
                id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
                titulo TEXT NOT NULL, contenido TEXT NOT NULL DEFAULT '',
                creada_en INTEGER NOT NULL)
        """)
        db.execSQL("""
            INSERT INTO notas_nueva (id, titulo, contenido, creada_en)
            SELECT id, titulo, COALESCE(contenido, ''), creada_en FROM notas
        """)
        db.execSQL("DROP TABLE notas")
        db.execSQL("ALTER TABLE notas_nueva RENAME TO notas")
        db.execSQL("CREATE INDEX index_notas_titulo ON notas (titulo)")
    }
}

Un detalle crítico: el esquema que dejes debe coincidir exactamente con el que Room espera, índices incluidos y con sus nombres canónicos. Room valida la estructura tras migrar, y una diferencia mínima en un índice aborta la apertura. El JSON exportado de la versión destino es la referencia para copiar esos nombres.

Probarlas: la única verificación que cuenta

Una migración que compila no demuestra nada. La biblioteca de tests de migración permite crear una base con el esquema de la versión antigua, poblarla con datos representativos, ejecutar la migración y validar el resultado.

@get:Rule
val helper = MigrationTestHelper(getInstrumentation(), AppDatabase::class.java)

@Test
fun migra_3_a_4_conservando_contenido() {
    helper.createDatabase(TEST_DB, 3).apply {
        execSQL("INSERT INTO notas (id, titulo, cuerpo, creada_en) VALUES (1, 'a', 'texto', 0)")
        close()
    }
    val db = helper.runMigrationsAndValidate(TEST_DB, 4, true, MIGRACION_3_4)
    db.query("SELECT contenido FROM notas WHERE id = 1").use {
        it.moveToFirst()
        assertEquals("texto", it.getString(0))
    }
}

El parámetro de validación compara el esquema resultante con el JSON de la versión destino: sin el directorio de esquemas versionado, este test no puede existir. Hay que probar también los saltos, porque un usuario que no abre la app en un año migrará de la 1 a la 5 de golpe, encadenando todas las migraciones intermedias.