Room 3.0

依存関係の宣言

Room3 への依存関係を追加するには、Google の Maven リポジトリをプロジェクトに追加する必要があります。詳しくは、Google の Maven リポジトリをご覧ください。

アプリまたはモジュールの build.gradle ファイルに、必要なアーティファクトの依存関係を追加します。

dependencies {
    val room_version = ""

    implementation("androidx.room3:room3-runtime:$room_version")
    ksp("androidx.room3:room3-compiler:$room_version")
}

dependencies {
    def room_version = ""

    implementation "androidx.room3:room3-runtime:$room_version"

    ksp "androidx.room3:room3-compiler:$room_version"
}

KSP プラグインの使用方法については、KSP クイックスタートのドキュメントをご覧ください。

依存関係について詳しくは、ビルド依存関係の追加をご覧ください。

Room Gradle プラグインを使用する

Room Gradle プラグインを使用して、Room コンパイラのオプションを構成できます。このプラグインは、生成されたスキーマ（コンパイル タスクの出力であり、自動移行に使用される）が再現可能でキャッシュ可能なビルドになるように、プロジェクトを構成します。

プラグインを追加するには、トップレベルの Gradle ビルドファイルで、プラグインとそのバージョンを定義します。

plugins {
    id 'androidx.room3' version "$room_version" apply false
}

plugins {
    id("androidx.room3") version "$room_version" apply false
}

モジュール レベルの Gradle ビルドファイルで、プラグインを適用して room3 拡張機能を使用します。

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

plugins {
    id("androidx.room3")
}

room3 {
    schemaDirectory("$projectDir/schemas")
}

Room Gradle プラグインを使用する場合は、schemaDirectory を設定する必要があります。これにより、Room コンパイラとさまざまなコンパイル タスクとそのバックエンド（kotlinc、KSP）が、スキーマ ファイルをフレーバー フォルダ（schemas/flavorOneDebug/com.package.MyDatabase/1.json など）に出力するように構成されます。これらのファイルは、検証と自動移行に使用するためにリポジトリにチェックインする必要があります。

フィードバック

お寄せいただいたフィードバックは Jetpack 改善の参考にさせていただきます。新しい問題が見つかった場合や、このライブラリを改善するアイデアをお持ちの場合は、お知らせください。新しい問題を報告していただく前に、このライブラリの既存の問題をご確認ください。スターボタンをクリックすると、既存の問題に投票できます。

新しい問題を報告する

詳細については、Issue Tracker のドキュメントをご覧ください。

バージョン 3.0

バージョン 3.0.0-alpha01

2026 年 3 月 11 日

androidx.room3:room3-*:3.0.0-alpha01 がリリースされました。

Room 3.0（パッケージ androidx.room3）は、Kotlin マルチプラットフォーム（KMP）に重点を置いた Room 2.x パッケージ（androidx.room）のメジャー バージョン アップデートです。

コア アノテーション API は、メイン コンポーネントとともに変更されません。

• androidx.room3.RoomDatabase を拡張し、@Database でアノテーションが付けられた抽象クラスは、Room のアノテーション プロセッサのエントリ ポイントです。
• データベース宣言には、データベース スキーマを記述する 1 つ以上のデータクラスがあり、@Entity アノテーションが付けられています。
• データベース オペレーションは、@Query アノテーションで SQL ステートメントが定義されているクエリ関数を含む @Dao 宣言で定義されます。
• ランタイムに、データベース実装は RoomDatabase.Builder を介して取得できます。この RoomDatabase.Builder はデータベースの構成にも使用されます。

Room を使用してローカル データベースにデータを保存するガイドのドキュメントのほとんどは、Room 3.0 にも関連しています。

Room 2.x との主な互換性のない変更点は次のとおりです。

• 新しいパッケージ androidx.room3。
• androidx.room3:room3-sqlite-wrapper を使用している場合を除き、SupportSQLite API はサポートされなくなりました。
• すべてのデータベース オペレーションがコルーチン API ベースになりました。
• Kotlin コードの生成のみ。
• Kotlin Symbol Processing（KSP）が必要です。

Room 3.0 では、重大な変更に加えて、2.x と比較して次のような新機能が導入されています。

• JS と WasmJS のサポート
• カスタム DAO の戻り値の型

新しいパッケージ

既存の Room 2.x 実装との互換性の問題や、Room への推移的依存関係を持つライブラリ（WorkManager など）との互換性の問題を回避するため、Room 3.0 は新しいパッケージに存在します。つまり、新しい Maven グループとアーティファクト ID もあります。たとえば、androidx.room:room-runtime は androidx.room3:room3-runtime になり、androidx.room.RoomDatabase などのクラスは androidx.room3.RoomDatabase に配置されます。

SupportSQLite API がない

Room 3.0 は SQLiteDriver API によって完全にサポートされており、SupportSQLiteDatabase などの SupportSQLite 型や Cursor などの Android 型を参照しなくなりました。SupportSQLiteDatabase をミラーリングする RoomDatabase API と SupportSQLiteOpenHelper を取得する API が削除されたため、Room 3.0 と 2.x の間で最も大きな変更が行われました。RoomDatabase をビルドするには、SQLiteDriver が必須になりました。

たとえば、データベースの直接操作用の API は、ドライバの同等のものに置き換えられます。

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

// Room 3.x
roomDatabase.withWriteTransaction { ... }

// Room 2.x
roomDatabase.query("SELECT * FROM Song").use { cursor -> ... }

// Room 3.x
roomDatabase.useReaderConnection { connection ->
  connection.usePrepared("SELECT * FROM Song") { stmt -> ... }
}

引数として SupportSQLiteDatabase を持つコールバック API も、引数として SQLiteConnection を持つ同等の API に置き換えられました。これらは、Migration.onMigrate() や AutoMigrationSpec.onPostMigrate() などの移行コールバック関数と、RoomDatabase.Callback.onCreate() や RoomDatabase.Callback.onOpen() などのデータベース コールバックです。

KMP プロジェクトで Room を使用していた場合は、インポート参照の更新が主な作業となるため、3.0 への移行は簡単です。それ以外の場合は、Android 専用の Room から KMP への移行と同じ移行戦略が適用されます。Room KMP 移行ガイドをご覧ください。

SupportSQLite ラッパー

Room 3.x では、移行を容易にするために 2.x で作成された SupportSQLite ラッパーが保持され、新しいアーティファクト androidx.room3:room3-sqlite-wrapper に配置されるようになりました。互換性 API を使用すると、RoomDatabase を SupportSQLiteDatabase に変換できます。roomDatabase.openHelper.writableDatabase の呼び出しは roomDatabase.getSupportWrapper() に置き換えることができます。

Kotlin とコルーチンを優先

ライブラリをより進化させるため、Room 3.0 では Kotlin コードのみが生成され、Kotlin Symbol Processor（KSP）のみが使用されます。Room 2.x と比較して、Room 3.0 では Java コードの生成と KAPT または JavaAP によるアノテーション プロセッサの構成はできなくなりました。KSP は Java ソースを処理でき、Room コンパイラはソース宣言が Java で記述されているデータベース、エンティティ、DAO のコードを生成します。Room の使用が集中し、コードベースの残りの部分に影響を与えることなく Kotlin Gradle プラグインと KSP を適用できるマルチモジュール プロジェクトを作成することをおすすめします。

Room 3.0 ではコルーチンの使用も必須です。具体的には、DAO 関数は、Flow やカスタム DAO 戻り値の型などのリアクティブ型を返す場合を除き、一時停止する必要があります。データベース オペレーションを実行する Room API も、RoomDatabase.useReaderConnection や RoomDatabase.useWriterConnection などの suspend 関数です。

Room 2.x とは異なり、Executor を使用して RoomDatabase を構成することはできなくなりました。代わりに、データベースのビルダーを介して CoroutineContext とディスパッチャーを提供できます。

Room 3.0 の InvalidationTracker API は Flow ベースです。InvalidationTracker.Observer は、関連する API addObserver および removeObserver とともに削除されました。データベース オペレーションに反応するメカニズムは、InvalidationTracker の createFlow() API を介して作成できるコルーチン Flow を使用します。

使用例:

fun getArtistTours(from: Date, to: Date): Flow<Map<Artist, TourState>> {
    return db.invalidationTracker.createFlow("Artist").map { _ ->
        val artists = artistsDao.getAllArtists()
        val tours = tourService.fetchStates(artists.map { it.id })
        associateTours(artists, tours, from, to)
    }
}

ウェブサポート

Room 3.0 リリースでは、KMP ターゲットとして JavaScript と WasmJs が追加されています。JavaScript と WasmJs も対象とする SQLiteDriver インターフェース（androidx.sqlite:sqlite）のリリースと、新しいアーティファクト androidx.sqlite:sqlite-web にある新しいドライバ WebWorkerSQLiteDriver を組み合わせることで、すべての主要な KMP プラットフォームを対象とする共通コードで Room を使用できます。

ウェブ プラットフォームの非同期の性質により、SQLiteStatement を引数として受け取る Room API はサスペンド関数になりました。これらの関数の例としては、Migration.onMigrate()、RoomDatabase.Callback.onCreate()、PooledConnection.usePrepared() などがあります。ドライバ API では、非同期 API はすべてのプラットフォームで共通であり、同期 API は非ウェブ ターゲットで共通です。そのため、ウェブをターゲットとしないプロジェクトでは、共通コードで同期 API（SQLiteDriver.open()、SQLiteConnection.prepare()、SQLiteStatement.step()）を引き続き使用できます。一方、ウェブのみを対象とするプロジェクトでは、非同期 API（SQLiteDriver.openAsync()、SQLiteConnection.prepareAsync()、SQLiteStatement.stepAsync()）を使用する必要があります。

便宜上、androidx.sqlite パッケージには、前述の API の同期名（SQLiteConnection.executeSQL を追加）を持つ一時停止拡張関数も追加されています。これらの API は、プロジェクトがウェブ プラットフォームと非ウェブ プラットフォームの両方をターゲットとする場合に推奨されます。これらの API は、プラットフォームに基づいて適切なバリアントを呼び出す expect / actual 宣言であるためです。これらは、Room のランタイムが使用する API であり、サポートされているすべてのプラットフォームの共通コードでドライバの使用を可能にします。

使用例:

import androidx.sqlite.executeSQL
import androidx.sqlite.step

roomDatabase.useWriterConnection { connection ->
    val deletedSongs = connection.usePrepared(
        "SELECT count(*) FROM Song"
    ) { stmt ->
        stmt.step()
        stmt.getLong(0)
    }
    connection.executeSQL("DELETE FROM Song")
    deletedSongs
}

WebWorkerSQLiteDriver は、SQLiteDriver の実装です。WebWorkerSQLiteDriver は、Web Worker と通信してメインスレッド外でデータベース オペレーションを実行し、Origin Private File System（OPFS）にデータベースを保存できるようにします。ドライバをインスタンス化するには、簡単な通信プロトコルを実装するワーカーが必要です。このプロトコルについては、WebWorkerSQLiteDriver KDoc で説明しています。

現在、WebWorkerSQLiteDriver には通信プロトコルを実装するデフォルトのワーカーは付属していませんが、例として、androidx コードベースにはプロジェクトで使用できるワーカー実装が含まれています。SQLite の WASM を使用し、データベースを OPFS に保存します。このワーカーの例はローカルの NPM パッケージとして公開されています。Kotlin が NPM 依存関係をサポートしているため、ワーカーを提供する小さな KMP モジュールを作成できます。

Room のローカル ウェブ ワーカーの使用方法を示す次の GitHub プロジェクトをご覧ください。

プロジェクトでワーカーを設定したら、ウェブ用の Room の設定は他のプラットフォームと同様です。

fun createDatabase(): MusicDatabase {
    return Room.databaseBuilder<MusicDatabase>("music.db")
        .setDriver(WebWorkerSQLiteDriver(createWorker()))
        .build()
}

fun createWorker() =
    Worker(js("""new URL("sqlite-web-worker/worker.js", import.meta.url)"""))

今後のバージョンのウェブ ドライバには、NPM で公開されたデフォルトのワーカーが含まれる可能性があり、ウェブの設定が簡素化されます。

カスタム DAO の戻り値の型

RxJava や Paging などのさまざまな DAO 戻り値の型の統合が、DAO 戻り値の型コンバータと呼ばれる Room 3.0 の新しい API を使用するように変換されました。DAO 戻り値の型コンバータ関数（@DaoReturnTypeConverter）を使用すると、DAO 関数の結果をアノテーション付き関数で定義されたカスタム型に変換できます。これらの関数を使用すると、クエリ結果をデータ オブジェクトに変換する Room の生成コードに参加できます。DAO 戻り値の型コンバータを含むクラスは、@Database または @Dao 宣言の @DaoReturnTypeConverters アノテーションを介して登録する必要があります。

たとえば、DAO クエリで PagingSource を返すようにするには、androidx.room3:room3-paging にあるコンバータ クラスを登録する必要があります。

@Dao
@DaoReturnTypeConverters(PagingSourceDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song)
    fun getSongsPaginated(): PagingSource<Int, Song>
}

既存の統合は、DAO 戻り値の型コンバータに移動されました。

列型コンバータと同様に、DAO 戻り値の型コンバータはアプリケーションで定義できます。たとえば、アプリケーションはウェブタイプ kotlin.js.Promise の @DaoReturnTypeConverter を宣言できます。

object PromiseDaoReturnTypeConverter {
    @DaoReturnTypeConverter([OperationType.READ, OperationType.WRITE])
    fun <T> convert(
        db: RoomDatabase,
        executeAndConvert: suspend () -> T
    ): Promise<T> {
        return db.getCoroutineScope().promise { executeAndConvert() }
    }
}

上記のコンバータを使用すると、DAO クエリ関数が Promise を返すことができます。

@Dao
@DaoReturnTypeConverters(PromiseDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song")
    fun getAllSongs(): Promise<List<Song>>
}

@DaoReturnTypeConverter 関数には、必要なパラメータの数とその型に関する要件がいくつかあります。使用可能なパラメータは次のとおりです。

• db: RoomDatabase:（省略可）RoomDatabase インスタンスへのアクセスを提供します。これは、追加のデータベース オペレーションの実行やコルーチン スコープへのアクセスに役立ちます。
• tableNames: Array<String>:（省略可）クエリのアクセスされたテーブルが含まれます。Room の InvalidationTracker.createFlow() API と組み合わせることで、オブザーバブル / リアクティブ型をサポートするのに役立ちます。
• rawQuery: RoomRawQuery:（省略可）実行時にクエリのインスタンスを含み、PagingSourceDaoReturnTypeConverter によって実装される LIMIT / OFFSET 戦略などの変換を可能にします。
• executeAndConvert: suspend () -> T:（必須）クエリを実行し、その結果をデータ オブジェクトに解析する Room 生成関数。

DAO 戻り値の型コンバータの作成要件について詳しくは、@DaoReturnTypeConverter API の KDoc をご覧ください。