Room 3.0

  
Biblioteka trwałości danych Room zapewnia warstwę abstrakcji nad SQLite, aby umożliwić bardziej niezawodny dostęp do bazy danych przy jednoczesnym wykorzystaniu pełnej mocy SQLite.
Najnowsza aktualizacja Wersja stabilna Wersja kandydująca do publikacji Wersja beta Wersja alfa
1 lipca 2026 r. 3.0.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:

Kotlin

dependencies {
    val room_version = "3.0.0"

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

Dynamiczny

dependencies {
    def room_version = "3.0.0"

    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 Gradle do obsługi Room

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 automatycznej 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ę.

Dynamiczny

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

Kotlin

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

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

Dynamiczny

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

Kotlin

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 przechowywać w repozytorium, aby można było ich używać do weryfikacji i automatycznej migracji.

Prześlij opinię

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

1 lipca 2026 r.

Publikacja androidx.room3:room3-*:3.0.0 Wersja 3.0.0 zawiera te zmiany.

Najważniejsze funkcje wersji 3.0.0:

Room 3.0 (pakiet androidx.room3) to aktualizacja do nowej wersji 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 używasz androidx.room3:room3-sqlite-wrapper.
  • Wszystkie operacje na bazie danych są teraz oparte na interfejsach API Coroutine.
  • Tylko generowanie kodu w języku Kotlin.
  • Wymagane jest przetwarzanie symboli w Kotlinie (KSP).

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

  • Obsługa JS i WasmJS
  • Niestandardowe typy zwracane przez DAO
  • Obsługa FTS5 za pomocą @Fts5 adnotacji
  • Obsługa domyślnych wartości parametrów w języku Kotlin
  • właściwość PrimaryKey.algorihtm, aby określić algorytm generowania klucza podstawowego.
  • Możliwość tworzenia tabel „WITHOUT ROWID”
  • Kolumna relacji złożonej z @Relation

Nowy pakiet

Aby uniknąć problemów ze zgodnością z istniejącymi implementacjami Room w wersji 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 zajęcia takie jak androidx.room.RoomDatabase będą teraz dostępne pod adresem androidx.room3.RoomDatabase.

Brak interfejsów API SupportSQLite

Biblioteka Room 3.0 jest w pełni oparta na interfejsach API SQLiteDriver i nie odwołuje się już do typów SupportSQLite, takich jak SupportSQLiteDatabase, ani do typów Androida, takich jak Cursor. Jest to najważniejsza zmiana między biblioteką Room w wersji 3.0 a wersją 2.x, ponieważ usunęliśmy interfejsy API RoomDatabase, które odzwierciedlały SupportSQLiteDatabase, oraz interfejs API do pobierania SupportSQLiteOpenHelper. Do utworzenia RoomDatabase wymagany jest teraz 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 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 utworzony w wersji 2.x moduł SupportSQLite, 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. Zalecamy utworzenie projektu z wieloma modułami, w którym użycie biblioteki Room jest skoncentrowane, a wtyczki Kotlin Gradle Plugin i KSP można zastosować bez wpływu na pozostałą część kodu.

Room 3.0 wymaga też używania korutyn, a w szczególności funkcje DAO 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 zawieszania, takimi jak 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 InvalidationTracker w Room 3.0 są oparte na Flow. Usunięto InvalidationTracker.Observer wraz z odpowiednimi interfejsami API addObserver i removeObserver. Mechanizm reagowania na operacje na bazie danych opiera się na przepływach 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 JavaScriptu i WasmJs, oraz nowego sterownika WebWorkerSQLiteDriver znajdującego się w nowym artefakcie androidx.sqlite:sqlite-web można używać biblioteki 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 zawieszania. Przykłady tych funkcji to Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() i inne. W interfejsach API sterownika interfejsy API 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, aby wykonywać operacje 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 kodzie źródłowym androidx znajduje się implementacja procesu roboczego, której można użyć w projekcie. Korzysta z SQLite's WASM i przechowuje bazę danych w OPFS. Przykładowy proces roboczy jest publikowany jako lokalny pakiet NPM i 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.

Zobacz ten projekt 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 DAO, takie jak integracje RxJava i Paging, zostały przekształcone w taki sposób, aby używać nowego interfejsu API w Room 3.0 o nazwie konwertery typów zwracanych DAO. Funkcja konwertująca typ zwracany przez DAO (@DaoReturnTypeConverter) umożliwia przekształcanie 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 typu zwracanego 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:

Zwracany typ Klasa konwertera Artefakt
PagingSource PagingSourceDaoReturnTypeConverter androidx.room3:room3-paging
Observable, Flowable, Completable, Single, Maybe RxDaoReturnTypeConverters androidx.room3:room3-rxjava3
ListenableFuture GuavaDaoReturnTypeConverter androidx.room3:room3-guava
LiveData LiveDataDaoReturnTypeConverter androidx.room3:room3-livedata

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

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

  • db: RoomDatabase: (Opcjonalnie) Zapewnia dostęp do RoomDatabaseinstancji, co może być przydatne do wykonywania dodatkowych operacji na bazie danych lub uzyskiwania dostępu do zakresu korutyny.
  • 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 @DaoReturnTypeConverterAPI.

Wersja 3.0.0-rc01

17 czerwca 2026 r.

Publikacja androidx.room3:room3-*:3.0.0-rc01 Wersja 3.0.0-rc01 zawiera te zmiany.

Nowe funkcje

  • Dodano obsługę parametrów z wartościami domyślnymi w klasach danych używanych w wynikach zapytań DAO. Właściwość, która reprezentuje kolumnę i jest częścią konstruktora z wartością domyślną, będzie uważana za opcjonalną, a kolumna w wyniku nie będzie wymagana. (34279a, b/70762008, b/193531601)

Zmiany w interfejsie API

  • Zmień nazwę @TypeConverter na @ColumnTypeConverter, aby lepiej odróżnić zakres konwersji i zachować symetrię z @DaoReturnTypeConverter. (I24420, b/438041176)
  • Dodano interfejs API dla dostarczonych niestandardowych typów zwracanych DAO @ProvidedDaoReturnTypeConveter. (I2a8ad, b/517485682)
  • Dodano właściwość PrimaryKey.algorihtm, aby określić algorytm generowania klucza podstawowego, gdy wartość PrimaryKey.autoGenerate jest ustawiona na „prawda”. (I57944, b/70053837)

Wersja 3.0.0-alpha06

3 czerwca 2026 r.

Publikacja androidx.room3:room3-*:3.0.0-alpha06 Wersja 3.0.0-alpha06 zawiera te zmiany.

Zmiany w interfejsie API

  • Dodaj nową właściwość adnotacji w @Entity o nazwie withoutRowId, która po ustawieniu wartości „true” utworzy tabelę SQLite za pomocą opcji WITHOUT ROWID. (Idb48e, b/472790803)

Wersja 3.0.0-alpha05

19 maja 2026 r.

Publikacja androidx.room3:room3-*:3.0.0-alpha05 Wersja 3.0.0-alpha05 zawiera te zmiany.

Zmiany w interfejsie API

  • Aktualizuje właściwości @Relation i @Junction tak, aby właściwości parentColumns i entityColumns były tablicą nazw kolumn, które mają być używane jako klucze do rozwiązywania relacji, co z kolei obsługuje złożone klucze relacji. (I92196, b/64247765)

Wersja 3.0.0-alpha04

6 maja 2026 r.

Publikacja androidx.room3:room3-*:3.0.0-alpha04 Wersja 3.0.0-alpha04 zawiera te zmiany.

Zmiany w interfejsie API

  • Dodaj interfejsy API, aby skonfigurować pulę połączeń Room. Funkcje konstruktora setSingleConnectionPool() i setMultipleConnectionPool() umożliwiają kontrolowanie maksymalnej liczby połączeń, które Room otworzy z bazą danych. (I9700d, b/438041176, b/432820350)
  • Usunięcie z publicznego interfejsu API konfiguracji DatabaseConfiguration, ponieważ żaden inny publiczny interfejs API nie odwoływał się do tej konfiguracji. (I5f1e9, b/438041176)

Poprawki błędów

  • Ogranicz cele internetowe do korzystania z jednej puli połączeń, aby uniknąć problemów z „zablokowaną bazą danych”, które występują w przypadku OPFS (b/496255935).
  • Ponowna próba naprawienia błędu „Metoda jest zbyt duża”, który występuje, gdy biblioteka Room generuje onValidateSchema o zbyt dużej wielkości. Funkcja jest dzielona na podstawie liczby instrukcji, ale pomiar nie jest precyzyjny. Jeśli ten błąd nadal występuje, możesz dostosować liczbę instrukcji, które Room będzie uwzględniać w podziale, za pomocą opcji procesora adnotacji room.validationSplitSize. Wartość domyślna to obecnie 300 instrukcji, więc jeśli problem nadal występuje, użyj mniejszej liczby (b/493708172).

Wersja 3.0.0-alpha03

8 kwietnia 2026 r.

Publikacja androidx.room3:room3-*:3.0.0-alpha03 Wersja 3.0.0-alpha03 zawiera te zmiany.

Zmiany w interfejsie API

  • Ustaw konstruktor bez argumentów klasy RoomDatabase jako publiczny, aby uniknąć ostrzeżenia Lint, gdy konstruktor jest przywoływany w deklaracji @Database. (I9bac2, b/494722261)
  • Dodaj wersję funkcji Room.inMemoryDatabaseBuilder i Room.databaseBuilder, która nie przyjmuje kontekstu Androida. W Room 3.0 potrzeba obiektu Context została znacznie ograniczona, dlatego udostępnienie go jako opcjonalnej wartości w klasie Builder ułatwia tworzenie baz danych w pamięci w kodzie wspólnym. (I5d502, b/438041176)

Poprawki błędów

  • Naprawiono błąd „kod jest zbyt duży” w przypadku kodu wygenerowanego na potrzeby JVM i Androida, gdy treść onValidateSchema funkcji była zbyt duża (b/493708172).

Wersja 3.0.0-alpha02

25 marca 2026 r.

Publikacja androidx.room3:room3-*:3.0.0-alpha02 Wersja 3.0.0-alpha02 zawiera te zmiany.

Nowe funkcje

  • Obsługa FTS5: dodaliśmy obsługę FTS5 do Room za pomocą adnotacji @Fts5. Obejmuje to nowe stałe dla tokenizatorów FTS5 (TOKENIZER_ASCII i TOKENIZER_TRIGRAM) oraz wyliczenie dla opcji FTS „detail” (FULL, COLUMN i NONE). (I90934, b/146824830)
  • Cele wywoływania w pomieszczeniu: dodano cele js, wasmJs, tvOS i watchOS do room3-paging. (Icffd3, b/432783733)

Zmiany w interfejsie API

  • WieloplatformoweclearAllTables(): ujednoliconeclearAllTables(), dzięki czemu są dostępne na wszystkich platformach. Została ona też przekształcona w funkcję suspend. (I434ae, b/322846465)
  • Destructive Migration: dodano domyślną wartość parametru do parametru dropAllTables w interfejsach API fallbackToDestructiveMigration. (Ica88b, b/438041176)

  • Zmiany w eksperymentalnych interfejsach API:

    1. Przeniesiono @ExperimentalRoomApi do room-common, aby umożliwić oznaczanie interfejsów API opartych na adnotacjach jako eksperymentalnych.

    2. Dodaliśmy eksperymentalny atrybut RoomWarning, aby pominąć wymaganie dotyczące atrybutu @ConstructedBy w deklaracji bazy danych Room. W takim przypadku wartość DatabaseConstructor nie zostanie wygenerowana, a implementację fabryczną należy podać za pomocą parametru DatabaseBuilder. (If5443)

Poprawki błędów

  • Paging Source: zaktualizowano PagingSourceDaoReturnTypeConverter, aby prawidłowo wskazywać, że funkcja convert jest przeznaczona do zapytań READ. (I3b067, b/139872302)

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 nowej wersji 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 używasz androidx.room3:room3-sqlite-wrapper.
  • Wszystkie operacje na bazie danych są teraz oparte na interfejsach API Coroutine.
  • Tylko generowanie kodu w języku Kotlin.
  • Wymagane jest przetwarzanie symboli w Kotlinie (KSP).

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

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

Nowy pakiet

Aby uniknąć problemów ze zgodnością z istniejącymi implementacjami Room w wersji 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 zajęcia takie jak androidx.room.RoomDatabase będą teraz dostępne pod adresem androidx.room3.RoomDatabase.

Brak interfejsów API SupportSQLite

Biblioteka Room 3.0 jest w pełni oparta na interfejsach API SQLiteDriver i nie odwołuje się już do typów SupportSQLite, takich jak SupportSQLiteDatabase, ani do typów Androida, takich jak Cursor. Jest to najważniejsza zmiana między biblioteką Room w wersji 3.0 a wersją 2.x, ponieważ usunęliśmy interfejsy API RoomDatabase, które odzwierciedlały SupportSQLiteDatabase, oraz interfejs API do pobierania SupportSQLiteOpenHelper. Do utworzenia RoomDatabase wymagany jest teraz 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 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 utworzony w wersji 2.x moduł SupportSQLite, 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. Zalecamy utworzenie projektu z wieloma modułami, w którym użycie biblioteki Room jest skoncentrowane, a wtyczki Kotlin Gradle Plugin i KSP można zastosować bez wpływu na pozostałą część kodu.

Room 3.0 wymaga też używania korutyn, a w szczególności funkcje DAO 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 zawieszania, takimi jak 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 InvalidationTracker w Room 3.0 są oparte na Flow. Usunięto InvalidationTracker.Observer wraz z odpowiednimi interfejsami API addObserver i removeObserver. Mechanizm reagowania na operacje na bazie danych opiera się na przepływach 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 JavaScriptu i WasmJs, oraz nowego sterownika WebWorkerSQLiteDriver znajdującego się w nowym artefakcie androidx.sqlite:sqlite-web można używać biblioteki 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 zawieszania. Przykłady tych funkcji to Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() i inne. W interfejsach API sterownika interfejsy API 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, aby wykonywać operacje 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 kodzie źródłowym androidx znajduje się implementacja procesu roboczego, której można użyć w projekcie. Korzysta z SQLite's WASM i przechowuje bazę danych w OPFS. Przykładowy proces roboczy jest publikowany jako lokalny pakiet NPM i 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.

Zobacz ten projekt 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 DAO, takie jak integracje RxJava i Paging, zostały przekształcone w taki sposób, aby używać nowego interfejsu API w Room 3.0 o nazwie konwertery typów zwracanych DAO. Funkcja konwertująca typ zwracany przez DAO (@DaoReturnTypeConverter) umożliwia przekształcanie 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 typu zwracanego 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:

Zwracany typ Klasa konwertera Artefakt
PagingSource PagingSourceDaoReturnTypeConverter androidx.room3:room3-paging
Observable, Flowable, Completable, Single, Maybe RxDaoReturnTypeConverters androidx.room3:room3-rxjava3
ListenableFuture GuavaDaoReturnTypeConverter androidx.room3:room3-guava
LiveData LiveDataDaoReturnTypeConverter androidx.room3:room3-livedata

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

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

  • db: RoomDatabase: (Opcjonalnie) Zapewnia dostęp do RoomDatabaseinstancji, co może być przydatne do wykonywania dodatkowych operacji na bazie danych lub uzyskiwania dostępu do zakresu korutyny.
  • 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 @DaoReturnTypeConverterAPI.