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-alpha04

2026 年 5 月 6 日

发布了 androidx.room3:room3-*:3.0.0-alpha04。版本 3.0.0-alpha04 中包含 这些提交内容。

API 变更

• 添加了用于配置 Room 连接池的 API。构建器函数 setSingleConnectionPool() 和 setMultipleConnectionPool() 可用于控制 Room 将打开到数据库的最大连接数。(I9700d, b/438041176, b/432820350)
• 从公共 API 中移除了 Room 的 DatabaseConfiguration，因为没有其他公共 API 引用该配置。(I5f1e9, b/438041176)

版本 3.0.0-alpha03

2026 年 4 月 8 日

发布了 androidx.room3:room3-*:3.0.0-alpha03。版本 3.0.0-alpha03 包含 以下提交内容。

API 变更

• 将 RoomDatabase 的无参数构造函数设为公开，以避免在 @Database 声明中引用该构造函数时出现 Lint 警告。(I9bac2, b/494722261)
• 添加了不接受 Android Context 的 Room.inMemoryDatabaseBuilder 和 Room.databaseBuilder 版本。在 Room 3.0 中，对 Context 的需求已大大降低，因此，将 Context 设为构建器的可选值可让您更轻松地在通用代码中创建内存数据库。(I5d502, b/438041176)

bug 修复

• 修复了当 onValidateSchema 函数的正文过大时，JVM 和 Android 生成的代码中出现的“代码过大”错误 (b/493708172)。

版本 3.0.0-alpha02

2026 年 3 月 25 日

发布了 androidx.room3:room3-*:3.0.0-alpha02。版本 3.0.0-alpha02 中包含 以下提交内容。

新功能

• FTS5 支持： 通过 @Fts5 注解向 Room 添加了 FTS5 支持。这包括 FTS5 tokenizer 的新常量（TOKENIZER_ASCII 和 TOKENIZER_TRIGRAM）以及“详细信息”FTS 选项的枚举（FULL、COLUMN 和 NONE）。(I90934, b/146824830)
• Room 分页目标： 向 room3-paging 添加了 js、wasmJs、tvOS 和 watchOS 目标。(Icffd3, b/432783733)

API 变更

• 多平台 clearAllTables()： 通用化了 clearAllTables()，使其可在所有平台上使用。它还被转换为 suspend 函数。(I434ae, b/322846465)
• 破坏性迁移： 向 fallbackToDestructiveMigration API 中的 dropAllTables 添加了默认参数值。(Ica88b, b/438041176)

• 实验性 API 变更：

  1. 将 @ExperimentalRoomApi 移到了 room-common，以允许将基于注解的 API 标记为实验性。

  2. 添加了实验性 RoomWarning，以禁止在 Room 数据库声明中要求使用 @ConstructedBy。在这种情况下，系统不会生成 DatabaseConstructor，并且必须通过 DatabaseBuilder 提供工厂实现。(If5443)

bug 修复

• 分页来源： 更新了 PagingSourceDaoReturnTypeConverter，以正确指明其转换函数适用于 READ 查询。(I3b067, b/139872302)

版本 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 声明中定义，该声明包含查询函数，其 SQL 语句通过 @Query 注解定义。
• 在运行时，可以通过 RoomDatabase.Builder 获取数据库实现，该实现还用于配置数据库。

使用 Room将数据保存到本地数据库指南中的大多数文档仍然 适用于 Room 3.0。

Room 2.x 之间的主要重大差异如下：

• 新软件包 androidx.room3。
• 不再支持 SupportSQLite API，除非您使用的是 androidx.room3:room3-sqlite-wrapper。
• 所有数据库操作现在都基于协程 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 已被移除。现在，必须使用 SQLiteDriver 才能构建 RoomDatabase。

例如，用于直接数据库操作的 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)
    }
}

Web 支持

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），当项目同时以 Web 和非 Web 平台为目标时，建议使用这些 API，因为这些 API 是预期 / 实际声明，将根据平台调用正确的变体。这些是 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 通信，以在主线程之外执行数据库操作，并支持将 数据库存储在 Origin Private File System (OPFS) 中。如需实例化驱动程序 需要一个实现简单通信协议的工作器，该 协议在 WebWorkerSQLiteDriver KDoc 中进行了说明。

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

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

在项目中设置工作器后，为 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 中使用名为 DAO 返回值类型转换器的新 API。DAO 返回值类型转换器函数 (@DaoReturnTypeConverter) 可将 DAO 函数的结果转换为带注解的函数定义的自定义类型。这些函数支持参与 Room 生成的代码，这些代码将查询结果转换为数据对象。包含 DAO 返回值类型转换器的类必须通过 @DaoReturnTypeConverters 注解在 @Database 或 @Dao 声明中进行注册。

例如，如需让 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 返回值类型 转换器的要求，请参阅 API 的 @DaoReturnTypeConverter KDoc。