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 repozytorium Maven Google.

Dodaj zależności od 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 krótkim wprowadzeniu 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 tak, aby generowane schematy (które są wynikiem zadań kompilacji i są używane do automatycznych migracji) były prawidłowo skonfigurowane do tworzenia 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")
}

W przypadku korzystania z wtyczki Room Gradle wymagane jest ustawienie parametru schemaDirectory. Spowoduje to skonfigurowanie kompilatora Room oraz różnych zadań kompilacji i ich backendów (kotlinc, KSP) tak, aby pliki schematu były zapisywane w folderach z wariantami, np. schemas/flavorOneDebug/com.package.MyDatabase/1.json. Te pliki należy dodać do repozytorium, aby można było ich używać do weryfikacji i automatycznych migracji.

Prześlij opinię

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

Utwórz nowy problem

Więcej informacji znajdziesz w dokumentacji narzędzia do śledzenia problemów Issue Tracker documentation.

Wersja 3.0

Wersja 3.0.0-alpha04

6 maja 2026 r.

Opublikowano wersję androidx.room3:room3-*:3.0.0-alpha04. Wersja 3.0.0-alpha04 zawiera te zmiany.

Zmiany w interfejsie API

• Dodaliśmy interfejsy API do konfigurowania puli 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)
• Usunęliśmy DatabaseConfiguration z publicznego interfejsu API Room, ponieważ żaden inny publiczny interfejs API nie odwoływał się do konfiguracji. (I5f1e9, b/438041176)

Wersja 3.0.0-alpha03

8 kwietnia 2026 r.

Opublikowano wersję androidx.room3:room3-*:3.0.0-alpha03. Wersja 3.0.0-alpha03 zawiera te zmiany.

Zmiany w interfejsie API

• Udostępniliśmy konstruktor bezargumentowy RoomDatabase, aby uniknąć ostrzeżenia lintera, gdy konstruktor jest używany w deklaracji @Database. (I9bac2, b/494722261)
• Dodaliśmy wersję Room.inMemoryDatabaseBuilder i Room.databaseBuilder, która nie przyjmuje kontekstu Androida. W Room 3.0 potrzeba kontekstu została znacznie ograniczona, dlatego udostępnienie go jako wartości opcjonalnej w konstruktorze ułatwia tworzenie baz danych w pamięci w kodzie wspólnym. (I5d502, b/438041176)

Poprawki błędów

• Naprawiliśmy błąd 'code too large' (kod jest zbyt duży) w kodzie wygenerowanym na JVM i Androidzie, gdy treść funkcji onValidateSchema była zbyt duża (b/493708172).

Wersja 3.0.0-alpha02

25 marca 2026 r.

Opublikowano wersję 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 w Room za pomocą adnotacji @Fts5. Obejmuje to nowe stałe dla tokenizerów FTS5 (TOKENIZER_ASCII i TOKENIZER_TRIGRAM) oraz wyliczenie dla opcji FTS „detail” (FULL, COLUMN, i NONE). (I90934, b/146824830)
• Cele paginacji Room: dodaliśmy cele js, wasmJs, tvOS i watchOS do room3-paging. (Icffd3, b/432783733)

Zmiany w interfejsie API

• Na wielu platformach clearAllTables(): ujednoliciliśmy funkcję clearAllTables(), dzięki czemu jest ona dostępna na wszystkich platformach. Została też przekształcona w funkcję suspend. (I434ae, b/322846465)
• Destructive Migration: dodaliśmy domyślną wartość parametru do dropAllTables w interfejsach API fallbackToDestructiveMigration. (Ica88b, b/438041176)

• Eksperymentalne zmiany w interfejsie API:

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

  2. Dodaliśmy eksperymentalne ostrzeżenie RoomWarning, aby pominąć wymaganie dotyczące @ConstructedBy w deklaracji bazy danych Room. W tym przypadku nie zostanie wygenerowany DatabaseConstructor, a implementację fabryki należy podać za pomocą DatabaseBuilder. (If5443)

Poprawki błędów

• Źródło paginacji: zaktualizowaliśmy PagingSourceDaoReturnTypeConverter, aby prawidłowo wskazywać, że jego funkcja konwersji jest przeznaczona do zapytań READ. (I3b067, b/139872302)

Wersja 3.0.0-alpha01

11 marca 2026 r.

Opublikowano wersję androidx.room3:room3-*:3.0.0-alpha01.

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

Główne interfejsy API adnotacji i główne komponenty pozostają takie same:

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

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

Główne różnice między Room 2.x to:

• Nowy pakiet androidx.room3.
• Interfejsy API SupportSQLite 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.
• Generowanie kodu tylko w języku Kotlin.
• Wymagane jest przetwarzanie symboli Kotlin (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 zapobiec problemom ze zgodnością z istniejącymi implementacjami Room 2.x i bibliotekami z zależnościami przechodnimi do 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ł się na 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

Room 3.0 jest w pełni obsługiwany 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. Jest to najważniejsza zmiana między Room 3.0 a 2.x, ponieważ usunięto 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 zostały zastąpione 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łań zwrotnych, które miały jako argument SupportSQLiteDatabase, zostały też zastąpione odpowiednikami, które mają jako argument SQLiteConnection. Są to funkcje wywołań zwrotnych 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 Room był używany 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 Room w projekcie tylko na Androida do KMP. Więcej informacji znajdziesz w przewodniku migracji do Room KMP Migration Guide.

SupportSQLite Wrapper

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

Kotlin i Coroutines

Aby ułatwić rozwój biblioteki, Room 3.0 generuje tylko kod Kotlin i jest tylko procesorem symboli Kotlin (KSP). W porównaniu z Room 2.x nie ma generowania kodu Java, a konfiguracja procesora adnotacji za pomocą KAPT lub JavaAP nie jest już możliwa w Room 3.0. Pamiętaj, że KSP może przetwarzać źródła Java, a kompilator Room będzie generować kod dla bazy danych, encji lub DAO, których deklaracje źródłowe są w języku Java. Zaleca się używanie projektu wielomodułowego, w którym użycie Room jest skoncentrowane, a wtyczkę Kotlin Gradle i KSP można zastosować bez wpływu na resztę bazy kodu.

Room 3.0 wymaga też użycia Coroutines, 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ą też funkcjami zawieszania, takimi jak RoomDatabase.useReaderConnection i RoomDatabase.useWriterConnection.

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

InvalidationTracker interfejsy API w Room 3.0 są oparte na Flow. InvalidationTracker.Observer został usunięty wraz z odpowiednimi interfejsami API addObserver i removeObserver. Mechanizm reagowania na operacje na bazie danych polega na użyciu Coroutine Flows, które można utworzyć za pomocą interfejsu API createFlow() 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)
    }
}

Obsługa internetu

Wersja Room 3.0 dodaje JavaScript i WasmJs jako cele KMP. W połączeniu z udostępnieniem interfejsów SQLiteDriver (androidx.sqlite:sqlite), które też są 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 API Room, które przyjmowały SQLiteStatement jako argument, są teraz funkcjami zawieszania. Przykładami tych funkcji są Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() i inne. W interfejsach API sterowników asynchroniczne interfejsy API są wspólne dla wszystkich platform, a synchroniczne – dla celów innych niż internetowe. Dlatego projekt, który nie jest przeznaczony dla internetu, może nadal używać synchronicznych interfejsów API (SQLiteDriver.open(), SQLiteConnection.prepare() i SQLiteStatement.step()) w kodzie wspólnym. Natomiast projekt, który jest przeznaczony tylko dla internetu, musi używać asynchronicznych interfejsów API (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() i SQLiteStatement.stepAsync()).

Dla wygody w pakiecie androidx.sqlite dodaliśmy też funkcje rozszerzenia zawieszania z synchronicznymi nazwami wymienionych interfejsów API (z dodatkiem SQLiteConnection.executeSQL). Zalecamy używanie tych interfejsów API, gdy projekt jest przeznaczony zarówno dla platform internetowych, jak i innych, ponieważ są to deklaracje expect / actual, które będą wywoływać odpowiedni wariant w zależności od platform. Są to interfejsy API używane przez środowisko wykonawcze Room, które umożliwiają używanie sterownika w kodzie wspólnym na wszystkich obsługiwanych platformach.

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 Origin Private File System (OPFS). Aby utworzyć instancję sterownika wymagany jest worker, który implementuje prosty protokół komunikacji. Protokół jest opisany w KDoc WebWorkerSQLiteDriver.

Obecnie WebWorkerSQLiteDriver nie zawiera domyślnego workera, który implementuje protokół komunikacji, ale na przykład w bazie kodu androidx znajduje się implementacja workera, której można użyć w projekcie. Używa ona SQLite's WASM i przechowuje bazę danych w OPFS. Przykładowy worker jest publikowany jako lokalny pakiet NPM, a dzięki obsłudze zależności NPM w Kotlin, można utworzyć mały moduł KMP, który będzie obsługiwał workera.

Zobacz ten projekt na GitHubie , który pokazuje, jak używać lokalnego workera internetowego w Room.

Gdy worker jest skonfigurowany w projekcie, konfiguracja Room dla internetu jest podobna do innych platform:

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ślnego workera opublikowanego w NPM, co ułatwi konfigurację internetową.

Niestandardowe typy zwracane przez DAO

Różne integracje typów zwracanych przez DAO, takie jak 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 konwertera typów zwracanych przez DAO (@DaoReturnTypeConverter) umożliwia przekształcenie wyniku funkcji DAO w typ niestandardowy zdefiniowany przez funkcję z adnotacją. Te funkcje umożliwiają uczestniczenie w wygenerowanym przez Room kodzie, który przekształca wyniki zapytań w obiekty danych. Klasy zawierające konwertery zwracanych typów przez DAO muszą być zarejestrowane za pomocą @DaoReturnTypeConverters adnotacji w @Database lub @Dao deklaracjach.

Aby na przykład zapytanie DAO zwracało 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 zwracanych typów przez 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 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:

• 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 coroutine.
• tableNames: Array<String>: (Opcjonalnie) zawiera tabele, do których odwołuje się zapytanie. Jest to przydatne do obsługi typów obserwowalnych / reaktywnych w połączeniu z interfejsem API InvalidationTracker.createFlow() w Room.
• rawQuery: RoomRawQuery: (Opcjonalnie) zawiera w czasie działania instancję zapytania, co umożliwia 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 w obiekty danych.

Więcej informacji o wymaganiach dotyczących tworzenia konwertera zwracanych typów przez DAO znajdziesz w KDoc interfejsu @DaoReturnTypeConverter API.