Комната 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 можно использовать плагин Room Gradle. Плагин настраивает проект таким образом, чтобы сгенерированные схемы (которые являются результатом задач компиляции и используются для автоматической миграции) были корректно сконфигурированы для обеспечения воспроизводимых и кэшируемых сборок.

Чтобы добавить плагин, в главном файле сборки 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. Сообщите нам, если вы обнаружите новые проблемы или у вас есть идеи по улучшению этой библиотеки. Пожалуйста, ознакомьтесь с существующими проблемами в этой библиотеке, прежде чем создавать новую. Вы можете проголосовать за существующую проблему, нажав кнопку со звездочкой.

Создать новую задачу

Для получения более подробной информации см. документацию по системе отслеживания ошибок .

Версия 3.0

Версия 3.0.0-alpha01

11 марта 2026 г.

Выпущена версия androidx.room3:room3-*:3.0.0-alpha01 .

Room 3.0 (пакет androidx.room3 ) — это крупное обновление версии пакета Room 2.x ( androidx.room ), ориентированное на многоплатформенную разработку на Kotlin (KMP).

Основные API для аннотирования, а также основные компоненты остаются неизменными:

• Абстрактный класс, расширяющий androidx.room3.RoomDatabase и аннотированный @Database является точкой входа для обработчика аннотаций Room.
• В объявлении базы данных содержится один или несколько классов данных, описывающих схему базы данных, и они аннотированы с помощью @Entity .
• Операции с базой данных определяются в объявлениях @Dao , содержащих функции запросов, SQL-запросы которых определяются с помощью аннотации @Query .
• Во время выполнения реализация базы данных может быть получена с помощью объекта RoomDatabase.Builder , который также используется для настройки базы данных.

Большая часть документации в руководстве «Сохранение данных в локальной базе данных с помощью Room» по-прежнему актуальна для Room 3.0.

Основные отличия Room 2.x от Room 2.x заключаются в следующем:

• Новый пакет, androidx.room3 .
• Поддержка API SupportSQLite прекращена, за исключением случаев использования androidx.room3:room3-sqlite-wrapper .
• Теперь все операции с базой данных выполняются с помощью API-интерфейсов сопрограмм.
• Генерация кода только для Kotlin.
• Требуется Kotlin Symbol Processing (KSP).

Помимо существенных изменений, Room 3.0 предлагает новые функции по сравнению с версией 2.x:

• Поддержка JavaScript и WasmJS
• Типы возвращаемых значений пользовательских DAO

Новая упаковка

Чтобы предотвратить проблемы совместимости с существующими реализациями Room 2.x и с библиотеками, имеющими транзитивные зависимости от Room (например, WorkManager), Room 3.0 находится в новом пакете, что означает наличие новой группы Maven и новых идентификаторов артефактов. Например, androidx.room:room-runtime теперь называется androidx.room3:room3-runtime , а такие классы, как androidx.room.RoomDatabase , теперь будут располагаться по адресу androidx.room3.RoomDatabase .

API SQLite не поддерживаются.

Room 3.0 полностью использует API SQLiteDriver и больше не ссылается на типы SupportSQLite , такие как SupportSQLiteDatabase , или типы Android, такие как Cursor . Это наиболее значительное изменение между Room 3.0 и 2.x, поскольку были удалены API RoomDatabase , которые дублировали SupportSQLiteDatabase , а также API для получения SupportSQLiteOpenHelper . Теперь для создания 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 -> ... }
}

API-функции обратного вызова, которые ранее принимали в качестве аргумента объект SupportSQLiteDatabase также были заменены эквивалентными API-функциями, принимающими в качестве аргумента объект SQLiteConnection . К ним относятся функции обратного вызова для миграций, такие как Migration.onMigrate() и AutoMigrationSpec.onPostMigrate() а также функции обратного вызова для баз данных, такие как RoomDatabase.Callback.onCreate() , RoomDatabase.Callback.onOpen() и т. д.

Если Room использовался в проекте KMP, то переход на версию 3.0 будет проще, поскольку в основном он включает обновление ссылок на импорт. В противном случае применяется та же стратегия миграции с Room, предназначенного только для Android, на KMP; см. руководство по миграции Room в KMP .

Оболочка SupportSQLite

В Room 3.x сохранена оболочка SupportSQLite, созданная в версии 2.x для упрощения миграции, и теперь она находится в новом артефакте androidx.room3:room3-sqlite-wrapper . API совместимости позволяет преобразовать RoomDatabase в SupportSQLiteDatabase . Вызовы roomDatabase.openHelper.writableDatabase можно заменить на roomDatabase.getSupportWrapper() .

Kotlin и корутины в первую очередь

Для более эффективного развития библиотеки Room 3.0 генерирует только код Kotlin и является лишь обработчиком символов Kotlin (KSP). По сравнению с Room 2.x, здесь отсутствует генерация кода Java, а настройка обработчика аннотаций через KAPT или JavaAP в Room 3.0 больше невозможна. Следует отметить, что KSP способен обрабатывать исходный код Java, и компилятор Room будет генерировать код для баз данных, сущностей или DAO, объявления исходного кода которых написаны на Java. Рекомендуется использовать многомодульный проект, где основное внимание уделяется Room, и где плагин Kotlin Gradle и KSP могут применяться без влияния на остальную кодовую базу.

Room 3.0 также требует использования корутин, и, в частности, функции DAO должны быть приостановлены, если они не возвращают реактивный тип, такой как Flow или пользовательский тип возвращаемого значения DAO. API Room для выполнения операций с базой данных также являются приостановленными функциями, например, RoomDatabase.useReaderConnection и RoomDatabase.useWriterConnection .

В отличие от Room 2.x, здесь больше нельзя настроить RoomDatabase с помощью Executor ; вместо этого можно предоставить CoroutineContext вместе с диспетчером через построитель базы данных.

API InvalidationTracker в Room 3.0 основаны на Flow (Flow), InvalidationTracker.Observer удален вместе с соответствующими API addObserver и removeObserver . Механизм реагирования на операции с базой данных осуществляется посредством сопрограммных потоков (Coroutine Flows), которые можно создать с помощью API createFlow() в InvalidationTracker .

Пример использования:

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. В сочетании с выпуском интерфейсов SQLiteDriver ( androidx.sqlite:sqlite ), которые также ориентированы на JavaScript и WasmJs, и новым драйвером WebWorkerSQLiteDriver расположенным в новом артефакте androidx.sqlite:sqlite-web , становится возможным использовать Room в общем коде, ориентированном на все основные платформы KMP.

В связи с асинхронной природой веб-платформ, API Room, принимавшие SQLiteStatement в качестве аргумента, теперь являются функциями с приостановкой. Примерами таких функций являются Migration.onMigrate() , RoomDatabase.Callback.onCreate() , PooledConnection.usePrepared() и другие. В API драйвера асинхронные API являются общими для всех платформ, а синхронные — общими для не веб-целей. Поэтому проект, не ориентированный на веб, может продолжать использовать синхронные API ( SQLiteDriver.open() , SQLiteConnection.prepare() и SQLiteStatement.step() ) в общем коде. В то же время проект, ориентированный только на веб, должен использовать асинхронные API ( SQLiteDriver.openAsync() , SQLiteConnection.prepareAsync() и SQLiteStatement.stepAsync() ).

Для удобства в пакет androidx.sqlite также добавлены функции расширения suspend с синхронными именами упомянутых API (с добавлением SQLiteConnection.executeSQL ). Эти API рекомендуются, если проект ориентирован как на веб-платформы, так и на не веб-платформы, поскольку они представляют собой объявления expect/actual, которые будут вызывать правильный вариант в зависимости от платформы. Это API, используемые средой выполнения Room и включающие использование драйвера в общем коде для всех поддерживаемых платформ.

Пример использования:

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 , которая взаимодействует с WebWorker для выполнения операций с базой данных вне основного потока и позволяет хранить базу данных в файловой системе Origin Private File System (OPFS). Для создания экземпляра драйвера требуется рабочий процесс, реализующий простой протокол связи; протокол описан в документации WebWorkerSQLiteDriver (KDoc ).

В настоящее время WebWorkerSQLiteDriver не поставляется с рабочим процессом по умолчанию, реализующим протокол связи, но в качестве примера можно привести кодовую базу androidx, содержащую реализацию рабочего процесса , которую можно использовать в вашем проекте. Она использует WASM SQLite и хранит базу данных в OPFS. Пример рабочего процесса опубликован как локальный пакет NPM, и благодаря поддержке зависимостей NPM в Kotlin можно создать небольшой модуль KMP для обслуживания рабочего процесса.

См. следующий проект на GitHub , демонстрирующий использование локального веб-воркера для Room.

После того как в проекте будет создан рабочий процесс, настройка Room for the Web будет аналогична настройке других платформ:

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

Различные интеграции типов возвращаемых значений DAO, такие как RxJava и Paging, были преобразованы для использования нового API в Room 3.0, называемого преобразователями типов возвращаемых значений DAO. Функция преобразователя типов возвращаемых значений 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>
}

Existing integrations have been moved to DAO return type converters:

Подобно преобразователям типов столбцов, преобразователи типов возвращаемых значений DAO могут быть определены приложением. Например, приложение может объявить аннотацию @DaoReturnTypeConverter для веб-типа kotlin.js.Promise .

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> : (Необязательно) Содержит таблицы, к которым обращался запрос, что полезно для поддержки наблюдаемых/реактивных типов в сочетании с API Room InvalidationTracker.createFlow() .
• rawQuery: RoomRawQuery : (Необязательно) Содержит во время выполнения экземпляр запроса, позволяющий выполнять преобразования, такие как стратегия LIMIT / OFFSET реализованная в PagingSourceDaoReturnTypeConverter .
• executeAndConvert: suspend () -> T : (Обязательно) Функция, сгенерированная Room, которая выполнит запрос и преобразует его результат в объекты данных.

Для получения дополнительной информации о требованиях к созданию преобразователя типов возвращаемых значений DAO см. документацию KDoc по API @DaoReturnTypeConverter .