How to Migrate from Room 2.x to Room 3.0: A Complete Migration Guide

Mar 14, 2026

I tried upgrading my Android app from Room 2.6.1 to Room 3.0 and immediately hit compilation errors. The migration wasn’t as simple as bumping version numbers.

Room 3.0 introduces Kotlin Multiplatform (KMP) support, which fundamentally changes how you structure your database code. This isn’t a minor update—it’s a major version bump with breaking changes.

Why Room 3.0 Changes Everything

Room 2.x was Android-only. Room 3.0 targets KMP, meaning your database layer can now be shared between Android, iOS, and other platforms.

This architectural shift requires rethinking where your database code lives and how it’s built.

The Migration Process

Step 1: Update Dependencies

Before (Room 2.x):

dependencies {
    implementation "androidx.room:room-runtime:2.6.1"
    kapt "androidx.room:room-compiler:2.6.1"
    implementation "androidx.room:room-ktx:2.6.1"
}

After (Room 3.0):

dependencies {
    implementation("androidx.room:room-runtime:3.0.0-alpha01")
    ksp("androidx.room:room-compiler:3.0.0-alpha01")
    implementation("androidx.room:room-ktx:3.0.0-alpha01")
}

Notice the switch from kapt to ksp. Room 3.0 recommends KSP (Kotlin Symbol Processing) for faster compilation.

Step 2: Restructure for KMP

If you want KMP support, move database code to commonMain:

@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

Platform-specific builders stay in platform source sets:

fun createDatabase(context: Context): AppDatabase {
    return Room.databaseBuilder(
        context,
        AppDatabase::class.java,
        "app-database"
    ).build()
}

fun createDatabase(): AppDatabase {
    return Room.inMemoryDatabaseBuilder<AppDatabase>()
        .build()
}

Step 3: Handle Breaking Changes

Room 3.0 deprecates and removes several APIs. Check the release notes for your specific version.

Common changes include:

DAO methods may require different return types
Database builder patterns changed for KMP compatibility
Some extension functions moved or renamed

What If You’re Not Ready for KMP?

You can still use Room 3.0 without KMP. Keep your existing Android-only structure:

@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

// Android-only usage
val db = Room.databaseBuilder(
    applicationContext,
    AppDatabase::class.java,
    "app-database"
).build()

This works fine. KMP support is opt-in.

Migration Checklist

Before deploying to production:

Read the official release notes for breaking changes
Update all Room dependencies to matching versions
Run your test suite completely
Check for deprecation warnings in IDE
Test on multiple Android versions
Increment your database version number if schema changed

Common Mistakes to Avoid

Migrating production apps to alpha releases. Room 3.0.0-alpha01 is not stable. Wait for at least a beta or stable release.

Ignoring deprecation warnings. Deprecated APIs may be removed in future versions. Address them now.

Forgetting to update database version. If you change entity structures, increment the database version and provide a migration path.

Not testing thoroughly. Major version bumps can introduce subtle bugs. Test all database operations.

When Should You Migrate?

Consider migrating when:

You need KMP support for iOS/Android code sharing
Room 3.0 reaches stable release
Your project targets Kotlin 2.0+
You want KSP’s faster compilation

For existing projects without KMP needs, staying on Room 2.x is perfectly fine until Room 3.0 stabilizes.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Room 3.0.0-alpha01 Release Notes
👨‍💻 r/androiddev - Jetpack Room 3.0 (alpha01): Some big changes ahead

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!