Room 3.0 Alpha: A Deep Dive into KMP‑Ready Database Overhaul and Migration Guide

Why Room 3.0? – Embracing KMP and Modernization

Since its inception, Room has been the default SQLite abstraction on Android. With Kotlin Multiplatform (KMP) maturing, the need for cross‑platform code reuse grew, but Room 2.x was tightly bound to the Android SupportSQLite API, blocking multi‑platform adoption.

The core motivations for Room 3.0 are twofold:

Embrace Kotlin Multiplatform (KMP) : Decouple from Android, allowing a single set of entities and DAOs to be shared across Android, iOS, JVM desktop, and even Web.

Comprehensive Modernization : Adopt a Kotlin‑first, coroutine‑centric model, drop legacy APIs and toolchains, and lay the groundwork for future feature iteration.

Core Changes – A Ground‑Breaking Refactor

1. Package Renaming

The library moves from the androidx.room package to androidx.room3, and the Maven Group ID changes accordingly. Example Gradle dependency migration:

// Room 2.x
val room_version = "2.6.1"
implementation("androidx.room:room-runtime:$room_version")
ksp("androidx.room:room-compiler:$room_version")

// Room 3.0
val room_version = "3.0.0-alpha01"
implementation("androidx.room3:room3-runtime:$room_version")
ksp("androidx.room3:room3-compiler:$room_version")

2. Replace SupportSQLite with androidx.sqlite Driver API

Room 3.0 drops the SupportSQLite API (e.g., SupportSQLiteDatabase, SupportSQLiteOpenHelper) and fully adopts the new androidx.sqlite driver. Consequences include:

Direct database APIs such as runInTransaction and query are removed. Room.databaseBuilder must now call setDriver() with a SQLiteDriver instance.

All callbacks now receive SQLiteConnection instead of SupportSQLiteDatabase.

Transaction API change example:

// Room 2.x
roomDatabase.runInTransaction {
    // ... business logic
}

// Room 3.0 (suspend function)
roomDatabase.withWriteTransaction {
    // ... business logic
}

To ease migration, Google provides a compatibility library androidx.room3:room3-sqlite-wrapper. It offers roomDatabase.getSupportWrapper() to obtain a temporary SupportSQLiteDatabase wrapper for legacy code.

3. KSP‑Only Processing

All annotation processing now uses Kotlin Symbol Processing (KSP); Java APT and KAPT are dropped.

Only Kotlin code is generated – no Java stubs.

Projects that still rely on Java must add the Kotlin Gradle plugin and KSP to continue using Room.

4. Coroutines as First‑Class Citizens

All DAO methods must be suspend unless they already return a reactive type such as Flow.

Executor‑based background configuration is replaced by RoomDatabase.Builder.setQueryCoroutineContext() to supply a CoroutineContext.

The old InvalidationTracker.Observer API is removed; use invalidaitonTracker.createFlow(tableNames) which returns a Flow.

Notable New Features

1. Custom DAO Return Types

Room 3.0 introduces the @DaoReturnTypeConverter annotation, allowing developers to define converters that map standard query results to any custom type. This replaces the previous limitation where only built‑in types (e.g., PagingSource, LiveData, RxJava) were supported.

@Database(
    entities = [Song::class],
    version = 1,
    typeConverters = [LiveDataDaoReturnTypeConverter::class, PagingSourceDaoReturnTypeConverter::class]
)
abstract class MusicDatabase : RoomDatabase()

2. Experimental Web Support

Leveraging androidx.sqlite, Room 3.0 adds an experimental library androidx.sqlite:sqlite-web that provides a WebWorkerSQLiteDriver. This driver runs on Web Workers with Origin Private File System (OPFS), enabling SQLite operations in browsers (JS/WASM) and opening a path for Android logic to be ported to the web.

How to Migrate Smoothly to Room 3.0

Migrate to KSP : If you still use KAPT, switch to KSP (supported since Room 2.4.0).

(Optional but recommended) Adopt the new SQLiteDriver API : Upgrade to Room 2.7.0+ first, replace all SupportSQLite usages with SQLiteDriver to reduce migration friction.

Upgrade dependencies to androidx.room3 : Change all androidx.room:* artifacts to androidx.room3:* in your build.gradle files.

Replace imports globally : Change import androidx.room.* to import androidx.room3.* throughout the codebase.

Adapt DAO methods to coroutines : Convert synchronous DAO functions to suspend and adjust call sites accordingly.

Handle remaining SupportSQLite dependencies : Add androidx.room3:room3-sqlite-wrapper and use getSupportWrapper() as a temporary bridge.

Register return‑type converters : For projects using Paging, RxJava, LiveData, or Guava, add the appropriate @DaoReturnTypeConverters annotations on @Database or @Dao.

Conclusion and Outlook

Room 3.0 is an ambitious update that elevates the library from an Android‑only component to a core piece of the Kotlin Multiplatform ecosystem. Although migration introduces breaking changes, the modernized API, coroutine‑first design, performance gains, and cross‑platform capabilities make the effort worthwhile.

Room 2.x has entered maintenance mode and will no longer receive new features, so Android developers should plan their migration to Room 3.0 soon.