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 编译器配置选项。 该插件会配置项目，以便生成的架构（编译任务的输出，用于自动迁移）正确配置为具有可重现且可缓存的 build。

如需添加插件，请在顶级 Gradle build 文件中定义插件及其版本。

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

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

在模块级 Gradle build 文件中，应用插件并使用 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。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 3.0

版本 3.0.0-alpha01

2026 年 3 月 11 日

发布了 androidx.room3:room3-*:3.0.0-alpha01。

Room 3.0（软件包 androidx.room3）是 Room 2.x 软件包 (androidx.room) 的重大版本更新，重点在于 Kotlin Multiplatform (KMP)。

核心注释 API 和主要组件保持不变：

• 扩展 androidx.room3.RoomDatabase 并使用 @Database 注解的抽象类是 Room 注解处理器的入口点。
• 数据库声明包含一个或多个描述数据库架构的数据类，并带有 @Entity 注解。
• 数据库操作在 @Dao 声明中定义，该声明包含通过 @Query 注解定义 SQL 语句的查询函数。
• 在运行时，可以通过 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)。

除了破坏性变更之外，与 2.x 相比，Room 3.0 还引入了以下新功能：

• 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 提供支持，不再引用 SupportSQLite 类型（例如 SupportSQLiteDatabase）或 Android 类型（例如 Cursor）。这是 Room 3.0 与 2.x 之间最重大的变化，因为与 SupportSQLiteDatabase 对应的 RoomDatabase API 以及用于获取 SupportSQLiteOpenHelper 的 API 已被移除。现在，构建 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 符号处理器 (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。

与 Room 2.x 不同，现在无法再使用 Executor 配置 RoomDatabase，而是可以通过数据库的构建器提供 CoroutineContext 以及调度程序。

Room 3.0 中的 InvalidationTracker API 基于 Flow，移除了 InvalidationTracker.Observer 及其相关 API addObserver 和 removeObserver。对数据库操作做出反应的机制是通过协程数据流实现的，该数据流可以通过 InvalidationTracker 中的 createFlow() API 创建。

用法示例：

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 版本添加了 JavaScript 和 WasmJs 作为 KMP 目标平台。结合还面向 JavaScript 和 WasmJs 的 SQLiteDriver 接口 (androidx.sqlite:sqlite) 的发布以及位于新制品 androidx.sqlite:sqlite-web 中的新驱动程序 WebWorkerSQLiteDriver，可以在面向所有主要 KMP 平台的通用代码中使用 Room。

由于 Web 平台的异步特性，以 SQLiteStatement 作为实参的 Room API 现在是挂起函数。这些函数的示例包括 Migration.onMigrate()、RoomDatabase.Callback.onCreate()、PooledConnection.usePrepared() 等。在驱动程序 API 中，异步 API 在所有平台上都很常见，而同步 API 则在非 Web 目标平台上很常见。因此，不以 Web 为目标平台的项目可以继续在通用代码中使用同步 API（SQLiteDriver.open()、SQLiteConnection.prepare() 和 SQLiteStatement.step()）。同时，仅以 Web 为目标平台的项目必须使用异步 API（SQLiteDriver.openAsync()、SQLiteConnection.prepareAsync() 和 SQLiteStatement.stepAsync()）。

为方便起见，androidx.sqlite 软件包还添加了具有上述 API 同步名称（添加了 SQLiteConnection.executeSQL）的 suspend 扩展函数。如果项目同时面向 Web 平台和非 Web 平台，建议使用这些 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 的一种实现，用于与 Web Worker 通信，以便在主线程之外执行数据库操作，并支持将数据库存储在源私有文件系统 (OPFS) 中。如需实例化驱动程序，需要一个实现简单通信协议的工作人员，该协议在 WebWorkerSQLiteDriver KDoc 中进行了说明。

目前，WebWorkerSQLiteDriver 不附带实现通信协议的默认工作器，但作为示例，androidx 代码库包含一个可在您的项目中使用的工作器实现。它使用 SQLite 的 WASM，并将数据库存储在 OPFS 中。示例 worker 以本地 NPM 软件包的形式发布，并且由于 Kotlin 支持 NPM 依赖项，因此可以创建一个小型 KMP 模块来为该 worker 提供服务。

请参阅以下 GitHub 项目，其中演示了如何将本地 Web Worker 用于 Room。

在项目中设置好 worker 后，为 Web 配置 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)"""))

未来版本的 Web 驱动程序可能会包含在 NPM 中发布的默认工作器，从而简化 Web 设置。

自定义 DAO 返回类型

各种 DAO 返回值类型集成（例如 RxJava 和 Paging 的集成）已转换为使用 Room 3.0 中的新 API，称为 DAO 返回值类型转换器。借助 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 返回值类型转换器也可以由应用定义。例如，应用可以为 Web 类型 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。