Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

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
9 września 2026 r.	3.0.3	-	-	3.1.0-alpha01

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 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 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 przekazać do repozytorium, aby można było ich używać do weryfikacji i automatycznych 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 dodać swój głos do istniejącego problemu, klikając przycisk gwiazdki.

Tworzenie nowego problemu

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

Wersja 3.1

Wersja 3.1.0-alpha01

9 września 2026 r.

Publikacja androidx.room3:room3-*:3.1.0-alpha01 Wersja 3.1.0-alpha01 zawiera te zmiany.

Zmiany w interfejsie API

Dodaliśmy setConnectionPoolTimeout(timeout: Duration) do RoomDatabase.Builder, aby umożliwić skonfigurowanie czasu oczekiwania puli połączeń. (I24d07, b/404380974)
Te adnotacje dotyczące pomieszczeń mają teraz AnnotationTarget.PROPERTY: @ColumnInfo, @PrimaryKey, @Relation, @Embedded, @Ignore i @ColumnTypeConverters. Te zmiany w interfejsie API sprawiają, że pokój jest „skupiony na właściwościach”, a nie „skupiony na polach”. Biblioteka Room może teraz używać właściwości bez pól pomocniczych jako reprezentacji kolumn encji lub kolumn wyników klasy danych zapytania. Właściwości muszą nadal mieć użyteczny getter i użyteczny setter lub być częścią głównego konstruktora, aby Room mógł ich używać w funkcjach DAO. (I72058, b/438041176, b/521861812)

Poprawki błędów

Rozwiązaliśmy problem w przypadku internetu i sterowników zawieszających, który polegał na tym, że anulowanie współprogramu podczas transakcji mogło spowodować nieprawidłowy stan bazy danych i połączenia, co uniemożliwiało dalsze korzystanie z nich. (If75c0, b/549860940)
Obsługa języka Kotlin object implementacja AutoMigrationSpec. (Id4077, b/215012591)
Naprawiono regresję, która powodowała, że Room zgłaszał wyjątek IllegalMonitorStateException podczas korzystania z funkcji DAO opakowania @Transaction. (I996d9, b/543285472, b/553140228)
Dodaliśmy obsługę wbudowanego konwertera typu kolumny dla kotlin.uuid.Uuid w Room. (Icca77, b/525093264)
Generator kodu Kotlin w bibliotece Room pomija teraz adnotacje OPT_IN_USAGE_ERROR i OPT_IN_USAGE w wygenerowanych klasach _Impl, co umożliwia interfejsom DAO i klasom Entity używanie typów z adnotacją @RequiresOptIn (takich jak kotlin.uuid.Uuid) bez konieczności używania adnotacji -opt-in w freeCompilerArgs. (I013bf, b/410607888)
Zapytania wstrzymujące Room i operacje narzędzia do śledzenia unieważnień będą teraz zgłaszać wyjątek IllegalStateException, gdy zostaną wywołane po zamknięciu bazy danych. (I5755a, b/543076356)
Naprawiono zakleszczenie, które może wystąpić w funkcjach zawieszania otoki @Transaction DAO, które przełączają kontekst i mają skonfigurowany element AndroidSQLiteDriver. (886ac5, b/543285472)
Naprawianie niepotrzebnego println() podczas przetwarzania. Dziękujemy Simonowi Marquisowi! (b/532893031)
Rozwiązanie problemu dotyczącego użycia innych baz danych w transakcji innej bazy danych, co powodowało nieokreślone zachowanie. (b/437068912)

Versja 3.0

Wersja 3.0.3

9 września 2026 r.

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

Poprawki błędów

Naprawiono regresję, która powodowała, że Room zgłaszał wyjątek IllegalMonitorStateException podczas korzystania z funkcji DAO opakowania @Transaction. (I996d9, b/543285472, b/553140228)
Rozwiązaliśmy problem w przypadku sterowników internetowych i zawieszania, który polegał na tym, że anulowanie współprogramu podczas transakcji mogło spowodować nieprawidłowy stan bazy danych i połączenia, co uniemożliwiało dalsze korzystanie z nich. (If75c0, b/549860940)

Wersja 3.0.2

26 sierpnia 2026 r.

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

Poprawki błędów

Zapytania wstrzymujące Room i operacje narzędzia do śledzenia unieważnień będą teraz zgłaszać wyjątek IllegalStateException, gdy zostaną wywołane po zamknięciu bazy danych. (I5755a, b/543076356)
Naprawiono zakleszczenie, które może wystąpić w funkcjach zawieszania otoki @Transaction DAO, które przełączają kontekst i mają skonfigurowany element AndroidSQLiteDriver. (886ac5, b/543285472)

Wersja 3.0.1

29 lipca 2026 r.

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

Poprawki błędów

Naprawianie niepotrzebnego println() podczas przetwarzania. Dziękujemy Simonowi Marquisowi! (b/532893031)
Rozwiązanie problemu dotyczącego użycia innych baz danych w transakcji innej bazy danych, co powodowało nieokreślone zachowanie. (b/437068912)

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 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 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 w języku 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
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 zapobiec problemom 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 klasy takie jak androidx.room.RoomDatabase będą teraz dostępne pod adresem androidx.room3.RoomDatabase.

Brak interfejsów API SupportSQLite

Room 3.0 w pełni korzysta z interfejsów 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 żądania RoomDatabase wymagane jest teraz żądanie 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 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 przeznaczonym tylko na Androida do KMP. Więcej informacji znajdziesz w przewodniku po migracji do Room KMP.

SupportSQLite Wrapper

Room w wersji 3.x zachowuje otok SupportSQLite utworzony w wersji 2.x, aby ułatwić migrację. Znajduje się 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 wielomodułowego, w którym skoncentrowane jest użycie biblioteki Room, a wtyczki 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, takie jak RoomDatabase.useReaderConnection i RoomDatabase.useWriterConnection, również są funkcjami zawieszania.

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.

InvalidationTracker Interfejsy API w Room 3.0 są Flow. InvalidationTracker.Observer został usunięty 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ć 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 takich 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()) we wspólnym kodzie. 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 interfejsu 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 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 zwracanych typów 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 zwracanych typów 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 zwracanego typu 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>>
}

@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 RoomDatabaseinstancji, 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 przydatne do obsługi typów obserwowalnych / reaktywnych w połączeniu z interfejsem InvalidationTracker.createFlow() API 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 uzyskać 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 „true”. (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ęto DatabaseConfiguration z publicznego interfejsu API, ponieważ żadna inna publiczna usługa API nie odwoływała 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 „bazą danych zablokowaną” występujących w przypadku OPFS (b/496255935).
Ponowna próba naprawienia błędu „Metoda jest zbyt duża”, który występuje, gdy Room generuje zbyt duży element onValidateSchema. Funkcja jest dzielona na podstawie liczby instrukcji, ale pomiar nie jest precyzyjny. Jeśli 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 kontekstu została znacznie ograniczona, dlatego udostępnienie go jako opcjonalnej wartości w przypadku narzędzia do tworzenia baz danych ułatwia tworzenie baz danych w pamięci w kodzie wspólnym. (I5d502, b/438041176)

Poprawki błędów

Naprawiono błąd „kod jest za duży” w przypadku kodu wygenerowanego na potrzeby JVM i Androida, gdy treść funkcji onValidateSchema 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 eksperymentalną adnotację RoomWarning, aby pominąć wymaganie dotyczące adnotacji @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 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 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 w języku 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

Brak interfejsów API SupportSQLite

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

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

Kotlin i korutyny na pierwszym miejscu

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

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
}

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

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

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 RoomDatabaseinstancji, 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 przydatne do obsługi typów obserwowalnych / reaktywnych w połączeniu z interfejsem InvalidationTracker.createFlow() API 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 uzyskać obiekty danych.

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