Room Database Migrations 2026: 5 Steps to Stop Crashes

I was in the middle of a release when our crash‑reporting dashboard lit up with dozens of **IllegalStateException: A migration from 1 to 3 was required** entries. The app had been on the Play Store for three years, the users were on Android 14, and the only thing that changed was that we had added a brand‑new `isPremium` column and renamed `userName` to `displayName`. One line of SQL in our `Migration(1, 3)` object was missing a `DEFAULT` clause, and the whole thing blew up on first launch for anyone who hadn’t already been on version 2. I spent three sleepless nights debugging a problem that could have been caught with a few extra tests and a bit more defensive code.

How to handle database migrations in Room, define a Migration class, and avoid crashes

To handle database migrations in Room, define a `Migration` class specifying the start and end versions, and override the `migrate` method to execute necessary SQL commands. Register this migration using the `addMigrations()` method in your `RoomDatabase.Builder`. Always provide a fallback strategy or test thoroughly to prevent crashes when schema versions change.

—

Understanding Room Database Migrations

The Role of SQLite in Room Architecture

Room is nothing more than a thin wrapper around SQLite. It generates table‑creation statements from your `@Entity` classes and hands them to an internal `SQLiteOpenHelper`. When the version number you pass to `Room.databaseBuilder()` bumps, the helper asks you for a migration path. If you don’t supply one, Room either throws an exception or, if you’ve called `fallbackToDestructiveMigration()`, wipes everything and starts fresh.

Why Manual Migrations are Error‑Prone

Most developers treat a migration like a one‑off script and never revisit it. The docs show a happy‑path `execSQL(“ALTER TABLE …”)`, but in the wild you’ll run into:

• Existing rows that violate a new **NOT NULL** constraint.
• Legacy devices on Android 15 that enforce stricter foreign‑key checks.
• Users who skip intermediate versions (the “router” problem).

The Android Developer Summit 2023‑2024 reported that improper migrations are the second‑most common cause of crash loops after runtime permission changes.

The Migration Lifecycle: FallBackToDestructive vs. Explicit Paths

When `RoomDatabase` opens, it:

1. Checks the stored `user_version` pragma.
2. Looks for a `Migration` object that matches `oldVersion → newVersion`.
3. If none is found, it either throws an `IllegalStateException` or falls back to destructive migration.

Explicit paths give you control; destructive fallback is a blunt instrument you should only use for development or when you can tolerate total data loss.

**My take:** I treat destructive migration as a last‑resort safety net for internal beta builds, never for production. The moment you ship a destructive fallback to a live app you’re betting that every user will accept a clean slate—something I’ve watched explode on launch day more than once.

—

Step 1: Updating Your Entity Definitions Safely

Adding New Columns with Default Values

// app/src/main/java/com/example/data/UserEntity.kt
// Room 2.6.1, Kotlin 1.9.0
@Entity(tableName = "users")
data class UserEntity(
    @PrimaryKey val id: Long,
    val displayName: String,
    @ColumnInfo(defaultValue = "0") // SQLite will use this for existing rows
    val isPremium: Int = 0
)

The `defaultValue` attribute makes SQLite fill the column for pre‑existing rows *before* the `NOT NULL` check runs. Forgetting it is a common source of the `android.database.sqlite.SQLiteConstraintException` you saw in the opening story.

Handling Non‑Null Constraints in Existing Databases

If you need a column that cannot be null **and** you don’t want a default, you must backfill data in the migration itself:

val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(database: SupportSQLiteDatabase) {
        try {
            database.execSQL("ALTER TABLE users ADD COLUMN lastLogin INTEGER")
            database.execSQL("UPDATE users SET lastLogin = strftime('%s','now')")
            database.execSQL("ALTER TABLE users ALTER COLUMN lastLogin SET NOT NULL")
        } catch (e: SQLException) {
            Log.e("RoomMigration", "Failed to add lastLogin", e)
            throw RuntimeException(e) // fail fast, let Room know the migration failed
        }
    }
}

Notice the `try‑catch` – we log and rethrow. Without it, the migration would silently stop at the first error, leaving the database half‑migrated and causing undefined behavior later.

Using @ColumnInfo for Schema Preservation

Renaming a property in Kotlin does **not** rename the underlying column. You must keep the original column name or write a migration that copies data:

@Entity(tableName = "users")
data class UserEntity(
    @PrimaryKey val id: Long,
    @ColumnInfo(name = "user_name") val displayName: String // keep old column name
)

If you decide to change the column name, add a migration that uses `ALTER TABLE … RENAME COLUMN …` (available starting SQLite 3.25, present on Android 14+).

—

Step 2: Implementing the Migration Class

Constructing the Migration Object

// app/src/main/java/com/example/data/AppDatabase.kt
// Room 2.6.1
val MIGRATION_3_4 = object : Migration(3, 4) {
    override fun migrate(database: SupportSQLiteDatabase) {
        // All SQL goes here
    }
}

You can chain multiple migrations in the builder:

Room.databaseBuilder(context, AppDatabase::class.java, "app-db")
    .addMigrations(MIGRATION_1_2, MIGRATION_2_3, MIGRATION_3_4)
    .build()

Writing Valid SQLite Queries (and verifying syntax)

SQLite’s `ALTER TABLE` is limited: you can add columns, rename tables, or rename columns (if the engine supports it). Anything else—changing a column type, dropping a column—requires a table copy.

override fun migrate(database: SupportSQLiteDatabase) {
    try {
        // 1️⃣ Add a new column
        database.execSQL(
            """
            ALTER TABLE orders 
            ADD COLUMN order_status TEXT NOT NULL DEFAULT 'PENDING'
            """.trimIndent()
        )
        // 2️⃣ Migrate existing data if needed
        database.execSQL(
            """
            UPDATE orders 
            SET order_status = CASE 
                WHEN shipped_at IS NOT NULL THEN 'SHIPPED' 
                ELSE 'PENDING' 
            END
            """.trimIndent()
        )
    } catch (e: SQLException) {
        Log.e("Migration_3_4", "SQL error", e)
        // Re‑throw to let Room abort the migration
        throw RuntimeException(e)
    }
}

Running the same statements against a fresh schema (using the **Room schema export** JSON) is a quick sanity check. I write a small JUnit test that opens an in‑memory DB at version 3, runs the migration, then queries `PRAGMA table_info(orders)` to ensure the column exists and the default is correct.

Registering Migrations in the Database Builder

Don’t forget to place the builder code where your DI framework creates the database—otherwise you’ll get the “migration required” crash at runtime.

@Module
@InstallIn(SingletonComponent::class)
object DatabaseModule {
    @Provides @Singleton
    fun provideDatabase(@ApplicationContext ctx: Context): AppDatabase =
        Room.databaseBuilder(ctx, AppDatabase::class.java, "app-db")
            .addMigrations(*AppDatabase.ALL_MIGRATIONS)
            .build()
}

The splat operator (`*`) spreads the array of migrations; it’s a tidy way to keep the list in one place.

—

Step 3: Testing Migrations with Espresso and Room Testing Library

Setting up the Migration Test Helper

Add the testing artifact to your `build.gradle.kts`:

// build.gradle.kts
dependencies {
    testImplementation("androidx.room:room-testing:2.6.1")
}

Then create a helper:

// app/src/androidTest/java/com/example/data/MigrationTest.kt
@RunWith(AndroidJUnit4::class)
class MigrationTest {
    private val TEST_DB = "migration-test-db"
    private lateinit var helper: MigrationTestHelper

    @Before
    fun setUp() {
        helper = MigrationTestHelper(
            InstrumentationRegistry.getInstrumentation(),
            AppDatabase::class.java.canonicalName,
            FrameworkSQLiteOpenHelperFactory()
        )
    }

Verifying Schema Integrity Post‑Migration

@Test
fun migrate1To3() {
    // 1️⃣ Create version 1 DB
    helper.createDatabase(TEST_DB, 1).apply {
        execSQL("INSERT INTO users (id, user_name) VALUES (1, 'alice')")
        close()
    }

    // 2️⃣ Run migration to version 3
    val migrated = helper.runMigrationsAndValidate(
        TEST_DB,
        3,
        true, // validate schema
        MIGRATION_1_2,
        MIGRATION_2_3
    )

    // 3️⃣ Verify data survived
    val cursor = migrated.query("SELECT isPremium FROM users WHERE id = 1")
    assertThat(cursor.moveToFirst()).isTrue()
    assertThat(cursor.getInt(0)).isEqualTo(0) // default value
    cursor.close()
}

The third argument (`true`) tells Room to compare the resulting schema against the compiled `schema/*.json` files. If you skip the JSON export, you’ll miss mismatches caused by a missing column.

Automating Pre‑Migration Database State Generation

Manually writing SQL for every old version is tedious. I generate the “old” DB by checking out a tag that corresponds to the version, running the app on an emulator, and dumping the DB file. A Gradle task copies the file into the test assets directory, so each CI run starts from a realistic snapshot.

—

Advanced Strategies: Multi‑Step and Incremental Migrations

Handling Version Jumps (v1 to v3) without Data Loss

Suppose a user skips the interim update because they were on Android 11 and only just upgraded to Android 14. Room will look for a *direct* migration path. You have two options:

1. **Chain migrations** – register `Migration(1,2)` **and** `Migration(2,3)`. Room will automatically execute them sequentially.
2. **Write a “router” migration** – a single `Migration(1,3)` that performs all necessary schema changes in one go.

I favor chaining for maintainability; the router is useful when you need to consolidate heavy data transformations that would otherwise be duplicated.

The Impact of Foreign Keys on Migration Complexity

Foreign‑key constraints are off by default on older Android versions. When you enable them (`PRAGMA foreign_keys=ON`), any `ALTER TABLE` that would temporarily violate a reference must be wrapped in a transaction that defers constraints.

override fun migrate(database: SupportSQLiteDatabase) {
    database.beginTransaction()
    try {
        database.execSQL("PRAGMA foreign_keys=OFF")
        // perform table recreation, copy data, then
        database.execSQL("PRAGMA foreign_keys=ON")
        database.setTransactionSuccessful()
    } finally {
        database.endTransaction()
    }
}

Skipping the `PRAGMA foreign_keys=OFF` step causes `SQLiteConstraintException` on devices that already enforce foreign‑key checks.

Complex Data Transformation During Migration (Type Converters)

When you change a column from `TEXT` to a JSON‑encoded blob, you need a custom `TypeConverter` **and** a migration that rewrites each row:

override fun migrate(database: SupportSQLiteDatabase) {
    database.execSQL("ALTER TABLE events ADD COLUMN payload_blob BLOB")
    val cursor = database.query("SELECT id, payload FROM events")
    while (cursor.moveToNext()) {
        val id = cursor.getLong(0)
        val json = cursor.getString(1)
        val blob = Gson().toJson(json).toByteArray()
        database.execSQL(
            "UPDATE events SET payload_blob = ? WHERE id = ?",
            arrayOf(blob, id)
        )
    }
    cursor.close()
    database.execSQL("ALTER TABLE events DROP COLUMN payload") // requires table rebuild
}

This pattern is CPU‑intensive; I always benchmark it on a low‑end Pixel 4a to confirm the migration finishes under 500 ms.

—

Production Troubleshooting and Error Handling

Analyzing “IllegalStateException: A migration from X to Y was required”

The stack trace points to `RoomOpenHelper` complaining about a missing path. Common culprits:

• Forgot to increment the `version` field in `@Database`.
• Registered the migration only in a debug build variant.
• Deployed an app bundle that excluded the migration class due to ProGuard/R8 rules.

**Fix:** Add a `-keep class androidx.room.migration.** { *; }` rule to your `proguard-rules.pro` and double‑check the version bump.

Recovering from a Failed Migration: Rollback Strategies

If a migration throws, Room aborts and the DB stays at the old version. You can catch the exception at the point you build the DB and fallback to a *manual* destructive migration that first backs up the user file:

try {
    Room.databaseBuilder(ctx, AppDatabase::class.java, "app-db")
        .addMigrations(*AppDatabase.ALL_MIGRATIONS)
        .build()
} catch (e: IllegalStateException) {
    Log.w("DatabaseInit", "Migration failed, attempting safe fallback", e)
    // Move the corrupt DB aside
    val corrupt = File(ctx.getDatabasePath("app-db").absolutePath + ".corrupt")
    ctx.getDatabasePath("app-db").renameTo(corrupt)
    // Recreate fresh DB
    Room.databaseBuilder(ctx, AppDatabase::class.java, "app-db")
        .fallbackToDestructiveMigration()
        .build()
}

You should also send a non‑intrusive telemetry event so you know how many users hit this path.

Destructive Migration: When it is acceptable and how to warn users

If your app stores only transient data (e.g., a cache of remote API objects) you can safely use `fallbackToDestructiveMigration()`. For anything user‑generated, you must warn the user or provide an export option.

if (needsDestructiveMigration) {
    showDialog(
        title = "Database Update Required",
        message = "We need to reset local data to continue. This will not affect your online account.",
        positiveButton = "Proceed"
    ) { proceed ->
        if (proceed) {
            // Re‑initialize DB