Room 3.0

Deklarowanie zależności

Aby dodać zależność od Room3, musisz dodać do projektu repozytorium Maven Google. Więcej informacji znajdziesz w artykule Repozytorium Maven Google.

Dodaj zależności dotyczące potrzebnych artefaktów w pliku build.gradle aplikacji lub modułu:

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"
}

Informacje o korzystaniu z wtyczki KSP znajdziesz w dokumentacji szybkiego wprowadzenia do KSP.

Więcej informacji o zależnościach znajdziesz w artykule Dodawanie zależności kompilacji.

Korzystanie z wtyczki Room Gradle

Za pomocą wtyczki Room Gradle możesz skonfigurować opcje kompilatora Room. Wtyczka konfiguruje projekt w taki sposób, aby wygenerowane schematy (które są wynikiem zadań kompilacji i są używane do automatycznych migracji) były prawidłowo skonfigurowane pod kątem powtarzalnych i możliwych do buforowania kompilacji.

Aby dodać wtyczkę, w pliku kompilacji Gradle najwyższego poziomu zdefiniuj wtyczkę i jej wersję.

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

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

W pliku kompilacji Gradle na poziomie modułu zastosuj wtyczkę i użyj rozszerzenia room3.

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

plugins {
    id("androidx.room3")
}

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

Ustawienie schemaDirectory jest wymagane, gdy używasz wtyczki Room Gradle. Spowoduje to skonfigurowanie kompilatora Room oraz różnych zadań kompilacji i ich backendów (kotlinc, KSP) w taki sposób, aby pliki schematu były zapisywane w folderach o określonych nazwach, np. schemas/flavorOneDebug/com.package.MyDatabase/1.json. Te pliki należy sprawdzić w repozytorium, aby można było ich używać do weryfikacji i automatycznej migracji.

Opinia

Twoja opinia pomoże nam ulepszyć Jetpacka. Jeśli odkryjesz nowe problemy lub masz pomysły na ulepszenie tej biblioteki, daj nam znać. Zanim utworzysz nową kartę, zapoznaj się z dotychczasowymi problemami w tej bibliotece. Możesz oddać głos na istniejący problem, klikając przycisk gwiazdki.

Tworzenie nowego problemu

Więcej informacji znajdziesz w dokumentacji narzędzia Issue Tracker.

Versja 3.0

Wersja 3.0.0-alpha01

11 marca 2026 r.

Publikacja androidx.room3:room3-*:3.0.0-alpha01

Room 3.0 (pakiet androidx.room3) to aktualizacja do wersji głównej pakietu Room 2.x (androidx.room), która koncentruje się na Kotlin Multiplatform (KMP).

Główne interfejsy API do adnotacji i ich główne komponenty pozostają bez zmian:

• Klasa abstrakcyjna, która rozszerza androidx.room3.RoomDatabase i jest opatrzona adnotacją @Database, jest punktem wejścia dla procesora adnotacji Room.
• Deklaracja bazy danych zawiera co najmniej jedną klasę danych opisującą schemat bazy danych i jest oznaczona adnotacją @Entity.
• Operacje na bazie danych są zdefiniowane w @Dao deklaracjach zawierających funkcje zapytań, których instrukcje SQL są zdefiniowane za pomocą adnotacji @Query.
• W czasie działania implementację bazy danych można uzyskać za pomocą elementu RoomDatabase.Builder, który służy też do konfigurowania bazy danych.

Większość dokumentacji w przewodniku Zapisywanie danych w lokalnej bazie danych za pomocą biblioteki Room jest nadal aktualna w przypadku biblioteki Room 3.0.

Główne różnice między wersją 2.x biblioteki Room są następujące:

• Nowy pakiet, androidx.room3.
• Interfejsy SupportSQLite API nie są już obsługiwane, chyba że korzystasz z androidx.room3:room3-sqlite-wrapper.
• Wszystkie operacje na bazie danych są teraz oparte na interfejsach API Coroutine.
• Generowanie kodu tylko w języku Kotlin.
• Wymagane jest przetwarzanie symboli w języku Kotlin (KSP).

Oprócz zmian powodujących niezgodność Room 3.0 wprowadza nowe funkcje w porównaniu z wersją 2.x:

• Obsługa JS i WasmJS
• Niestandardowe typy zwracane przez obiekty DAO

Nowy pakiet

Aby zapobiec problemom ze zgodnością z istniejącymi implementacjami Room 2.x i bibliotekami z zależnościami przechodnimi od Room (np. WorkManager), Room 3.0 znajduje się w nowym pakiecie, co oznacza, że ma też nową grupę Maven i identyfikatory artefaktów. Na przykład androidx.room:room-runtime zmieniło się w androidx.room3:room3-runtime, a klasy takie jak androidx.room.RoomDatabase będą teraz znajdować się w androidx.room3.RoomDatabase.

Brak interfejsów API SupportSQLite

Biblioteka Room 3.0 jest w pełni obsługiwana przez interfejsy API SQLiteDriver i nie odwołuje się już do typów SupportSQLite, takich jak SupportSQLiteDatabase, ani do typów Androida, takich jak Cursor. To najważniejsza zmiana między wersjami 3.0 i 2.x biblioteki Room, ponieważ usunęliśmy interfejsy API RoomDatabase, które odzwierciedlały SupportSQLiteDatabase, oraz interfejs API do pobierania SupportSQLiteOpenHelper. Do utworzenia RoomDatabase jest teraz wymagany SQLiteDriver.

Na przykład interfejsy API do bezpośrednich operacji na bazie danych są zastępowane odpowiednikami sterowników:

// 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 -> ... }
}

Interfejsy API wywołania zwrotnego, które miały jako argument SupportSQLiteDatabase, zostały również zastąpione odpowiednikami z argumentem SQLiteConnection. Są to funkcje wywołania zwrotnego migracji, takie jak Migration.onMigrate() i AutoMigrationSpec.onPostMigrate(), oraz wywołania zwrotne bazy danych, takie jak RoomDatabase.Callback.onCreate(), RoomDatabase.Callback.onOpen() itp.

Jeśli biblioteka Room była używana w projekcie KMP, migracja do wersji 3.0 jest prostsza, ponieważ polega głównie na aktualizacji odwołań do importu. W przeciwnym razie obowiązuje ta sama strategia migracji z biblioteki Room w projekcie przeznaczonym tylko na Androida do projektu KMP. Więcej informacji znajdziesz w przewodniku po migracji do biblioteki Room w projekcie KMP.

SupportSQLite Wrapper

Room w wersji 3.x zachowuje otok SupportSQLite utworzony w wersji 2.x, aby ułatwić migrację. Znajduje się on teraz w nowym artefakcie androidx.room3:room3-sqlite-wrapper. Interfejs API zgodności umożliwia przekształcenie RoomDatabase w SupportSQLiteDatabase. Wywołania funkcji roomDatabase.openHelper.writableDatabase można zastąpić wywołaniami funkcji roomDatabase.getSupportWrapper().

Kotlin i korutyny na pierwszym miejscu

Aby ulepszyć bibliotekę, Room 3.0 generuje tylko kod w języku Kotlin i jest tylko procesorem symboli Kotlin (KSP). W porównaniu z Room 2.x w Room 3.0 nie ma generowania kodu Java ani konfiguracji procesora adnotacji za pomocą KAPT lub JavaAP. Pamiętaj, że KSP może przetwarzać źródła w Javie, a kompilator Room będzie generować kod dla baz danych, encji lub obiektów DAO, których deklaracje źródłowe są w Javie. Zaleca się utworzenie projektu z wieloma modułami, w którym użycie biblioteki Room jest skoncentrowane, a wtyczkę Kotlin Gradle Plugin i KSP można zastosować bez wpływu na pozostałą część bazy kodu.

Room 3.0 wymaga też używania korutyn, a dokładniej funkcji DAO, które muszą być zawieszane, chyba że zwracają typ reaktywny, np. Flow lub niestandardowy typ zwracany przez DAO. Interfejsy API Room do wykonywania operacji na bazie danych są również funkcjami zawieszającymi, np. RoomDatabase.useReaderConnection i RoomDatabase.useWriterConnection.

W przeciwieństwie do Room 2.x nie można już konfigurować RoomDatabase za pomocą Executor. Zamiast tego można podać CoroutineContext wraz z dyspozytorem za pomocą narzędzia do tworzenia bazy danych.

Interfejsy API w Room 3.0 są oparte na Flow.InvalidationTracker.Observer został usunięty wraz z odpowiednimi interfejsami APIaddObserver i removeObserver.InvalidationTracker Mechanizm reagowania na operacje na bazie danych działa za pomocą przepływów współprogramów, które można tworzyć za pomocą interfejsu createFlow() API w InvalidationTracker.

Przykład użycia:

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)
    }
}

Pomoc w internecie

W wersji 3.0 biblioteki Room dodano JavaScript i WasmJs jako platformy docelowe KMP. W połączeniu z udostępnieniem interfejsów SQLiteDriver (androidx.sqlite:sqlite), które są też przeznaczone dla JavaScript i WasmJs, oraz nowego sterownika WebWorkerSQLiteDriver znajdującego się w nowym artefakcie androidx.sqlite:sqlite-web można używać Room w kodzie wspólnym, który jest przeznaczony dla wszystkich głównych platform KMP.

Ze względu na asynchroniczny charakter platform internetowych interfejsy Room API, które przyjmowały argument SQLiteStatement, są teraz funkcjami zawieszonymi. Przykłady tych funkcji to Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() i inne. W interfejsach API sterownika interfejsy asynchroniczne są powszechne na wszystkich platformach, a synchroniczne – na platformach innych niż internetowe. Dlatego projekt, który nie jest przeznaczony na platformę internetową, może nadal używać synchronicznych interfejsów API (SQLiteDriver.open(), SQLiteConnection.prepare() i SQLiteStatement.step()) w kodzie wspólnym. Projekt, który jest kierowany tylko na internet, musi korzystać z asynchronicznych interfejsów API (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() i SQLiteStatement.stepAsync()).

Dla wygody pakiet androidx.sqlite zawiera też funkcje rozszerzenia zawieszenia o synchronicznych nazwach wymienionych interfejsów API (z dodatkiem SQLiteConnection.executeSQL). Te interfejsy API są zalecane, gdy projekt jest przeznaczony zarówno na platformy internetowe, jak i nieinternetowe, ponieważ interfejsy API są deklaracjami expect / actual , które wywołują odpowiedni wariant w zależności od platformy. Są to interfejsy API używane przez środowisko wykonawcze Room, które umożliwiają korzystanie ze sterowników w kodzie wspólnym dla wszystkich obsługiwanych platform.

Przykład użycia:

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 to implementacja SQLiteDriver, która komunikuje się z Web Workerem w celu wykonywania operacji na bazie danych poza głównym wątkiem i umożliwia przechowywanie bazy danych w systemie plików OPFS (Origin Private File System). Aby utworzyć instancję sterownika, wymagany jest proces roboczy, który implementuje prosty protokół komunikacji. Protokół ten jest opisany w dokumentacji KDoc sterownika WebWorkerSQLiteDriver.

Obecnie WebWorkerSQLiteDriver nie zawiera domyślnego procesu roboczego, który implementuje protokół komunikacyjny, ale na przykład w bazie kodu androidx znajduje się implementacja procesu roboczego, której można użyć w projekcie. Korzysta z SQLite w WASM i przechowuje bazę danych w OPFS. Przykładowy proces roboczy jest publikowany jako lokalny pakiet NPM, a dzięki obsłudze zależności NPM w Kotlinie można utworzyć mały moduł KMP, który będzie obsługiwać proces roboczy.

Zapoznaj się z tym projektem na GitHubie, który pokazuje, jak używać lokalnego procesu roboczego w Room.

Po skonfigurowaniu pracownika w projekcie konfiguracja Room for the Web jest podobna do konfiguracji na innych platformach:

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)"""))

Przyszła wersja sterownika internetowego może zawierać domyślny proces roboczy opublikowany w NPM, co uprości konfigurację internetową.

Niestandardowe typy zwracanych wartości DAO

Różne integracje typów zwracanych przez DAO, takie jak integracje RxJava i Paging, zostały przekształcone tak, aby używać nowego interfejsu API w Room 3.0 o nazwie konwertery typów zwracanych przez DAO. Funkcja konwertująca typ zwracany przez DAO (@DaoReturnTypeConverter) umożliwia przekształcenie wyniku funkcji DAO w typ niestandardowy zdefiniowany przez funkcję z adnotacją. Funkcje te umożliwiają korzystanie z wygenerowanego przez Room kodu, który przekształca wyniki zapytań w obiekty danych. Klasy zawierające konwertery typów zwracanych przez DAO muszą być zarejestrowane za pomocą adnotacji @DaoReturnTypeConverters w deklaracjach @Database lub @Dao.

Aby na przykład zapytanie DAO zwracało wartość PagingSource, należy zarejestrować klasę konwertera znajdującą się w androidx.room3:room3-paging:

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

Istniejące integracje zostały przeniesione do konwerterów typu zwracanego DAO:

Podobnie jak konwertery typów kolumn, konwertery typów zwracanych przez DAO mogą być definiowane przez aplikację. Na przykład aplikacja może zadeklarować @DaoReturnTypeConverter dla typu internetowego 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() }
    }
}

Powyższy konwerter umożliwia następnie funkcjom zapytań DAO zwracanie wartości Promise:

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

@DaoReturnTypeConverter Funkcja ma kilka wymagań dotyczących liczby parametrów i ich typów. Możliwe parametry to:

• db: RoomDatabase: (Opcjonalnie) Zapewnia dostęp do instancji RoomDatabase, co może być przydatne do wykonywania dodatkowych operacji na bazie danych lub uzyskiwania dostępu do zakresu współprogramu.
• tableNames: Array<String>: (Opcjonalnie) Zawiera tabele, do których uzyskano dostęp w zapytaniu. Jest przydatny do obsługi typów obserwowalnych / reaktywnych w połączeniu z interfejsem InvalidationTracker.createFlow() API biblioteki Room.
• rawQuery: RoomRawQuery: (Opcjonalnie) Zawiera w czasie działania instancję zapytania, umożliwiając przekształcenia, takie jak strategia LIMIT / OFFSET zaimplementowana przez PagingSourceDaoReturnTypeConverter.
• executeAndConvert: suspend () -> T: (Wymagane) Wygenerowana przez Room funkcja, która wykona zapytanie i przeanalizuje jego wynik, aby przekształcić go w obiekty danych.

Więcej informacji o wymaganiach dotyczących tworzenia konwertera typu zwracanego DAO znajdziesz w dokumentacji KDoc interfejsu API @DaoReturnTypeConverter.