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 dokumentacji 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 wygenerowane 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 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 sprawdzić w 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 dodać swój głos do istniejącego problemu, 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-rc01

17 czerwca 2026 r.

Ukazała się wersja 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

• Zmieniono 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 PrimaryKey.autoGenerate jest ustawione na true. (I57944, b/70053837)

Wersja 3.0.0-alpha06

3 czerwca 2026 r.

Ukazała się wersja 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 na true utworzy tabelę SQLite z opcją WITHOUT ROWID. (Idb48e, b/472790803)

Wersja 3.0.0-alpha05

19 maja 2026 r.

Ukazała się wersja androidx.room3:room3-*:3.0.0-alpha05. Wersja 3.0.0-alpha05 zawiera te zmiany.

Zmiany w interfejsie API

• Zaktualizowano @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 umożliwia obsługę złożonych kluczy relacji. (I92196, b/64247765)

Wersja 3.0.0-alpha04

6 maja 2026 r.

Ukazała się wersja androidx.room3:room3-*:3.0.0-alpha04. Wersja 3.0.0-alpha04 zawiera te zmiany.

Zmiany w interfejsie API

• Dodaj 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)
• Usuń DatabaseConfiguration z publicznego interfejsu API Room, ponieważ żaden inny publiczny interfejs API nie odwoływał się do konfiguracji. (I5f1e9, b/438041176)

Poprawki błędów

• Ogranicz docelowe miejsca docelowe do korzystania z jednej puli połączeń, aby uniknąć problemów z „zablokowaną bazą danych”, które występują w przypadku OPFS (b/496255935).
• Spróbuj (ponownie) naprawić błąd „Metoda jest zbyt duża”, który występuje, ponieważ Room generuje zbyt dużą funkcję onValidateSchema. Funkcja jest dzielona na podstawie liczby instrukcji, ale pomiar nie jest dokładny. 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 jest obecnie ustawiona na 300 instrukcji, dlatego jeśli problem nadal występuje, użyj mniejszej liczby (b/493708172).

Wersja 3.0.0-alpha03

8 kwietnia 2026 r.

Ukazała się wersja androidx.room3:room3-*:3.0.0-alpha03. Wersja 3.0.0-alpha03 zawiera te zmiany.

Zmiany w interfejsie API

• Ustaw konstruktor bez argumentów RoomDatabase jako publiczny, aby uniknąć ostrzeżenia Lint, gdy konstruktor jest przywoływany w deklaracji @Database. (I9bac2, b/494722261)
• Dodaj wersję Room.inMemoryDatabaseBuilder i Room.databaseBuilder, która nie przyjmuje kontekstu Androida. Potrzeba kontekstu została znacznie ograniczona w Room 3.0, dlatego ustawienie go jako wartości opcjonalnej dla konstruktora umożliwia łatwiejsze tworzenie baz danych w pamięci w kodzie wspólnym. (I5d502, b/438041176)

Poprawki błędów

• Napraw błąd „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.

Ukazała się wersja androidx.room3:room3-*:3.0.0-alpha02. Wersja 3.0.0-alpha02 zawiera te zmiany.

Nowe funkcje

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

Zmiany w interfejsie API

• Wieloplatformowa funkcja clearAllTables(): ujednolicono 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: dodano domyślną wartość parametru do dropAllTables w interfejsach API fallbackToDestructiveMigration. (Ica88b, b/438041176)

• Eksperymentalne zmiany w interfejsie API:

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

  2. Dodano eksperymentalne ostrzeżenie RoomWarning, aby pominąć wymaganie dotyczące @ConstructedBy w deklaracji bazy danych Room. W takim przypadku DatabaseConstructor nie zostanie wygenerowany, a implementacja fabryki musi zostać udostępniona za pomocą DatabaseBuilder. (If5443)

Poprawki błędów

• Źródło stronicowania: zaktualizowano 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.

Ukazała się wersja androidx.room3:room3-*:3.0.0-alpha01.

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

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

• Klasa abstrakcyjna, która rozszerza androidx.room3.RoomDatabase i jest oznaczona 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 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ść dokumentacji 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 są następujące:

• 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 DAO

Nowy pakiet

Aby zapobiec problemom ze zgodnością z dotychczasowymi 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 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łań zwrotnych, które miały jako argument SupportSQLiteDatabase, zostały też zastąpione odpowiednimi interfejsami API, 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 wersji tylko na Androida do KMP. Więcej informacji znajdziesz w przewodniku migracji Room KMP.

SupportSQLite Wrapper

Room 3.x zachowuje otokę SupportSQLite utworzoną w wersji 2.x, aby ułatwić migrację. 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 First

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. Zalecamy stosowanie projektu wielomodułowego, w którym użycie Room jest skoncentrowane, a wtyczkę Kotlin Gradle i KSP można zastosować bez wpływu na pozostałą część 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 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 za pomocą konstruktora bazy danych można podać CoroutineContext wraz z dyspozytorem.

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 miejsca docelowe KMP. W połączeniu z wydaniem 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 na wszystkich platformach, a synchroniczne – na platformach innych niż internetowe. Dlatego projekt, który nie jest przeznaczony na internet, 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 na internet, musi używać asynchronicznych interfejsów API (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() i SQLiteStatement.stepAsync()).

Dla wygody pakiet androidx.sqlite dodał też funkcje rozszerzające zawieszanie z synchronicznymi nazwami wymienionych interfejsów API (z dodatkiem SQLiteConnection.executeSQL). Te interfejsy API są zalecane, gdy projekt jest przeznaczony zarówno na platformy internetowe, jak i inne, 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 proces roboczy, który implementuje prosty protokół komunikacji. Protokół jest opisany w KDoc WebWorkerSQLiteDriver.

Obecnie WebWorkerSQLiteDriver nie jest dostarczany z domyślnym procesem roboczym, który implementuje protokół komunikacji, ale na przykład w bazie kodu androidx znajduje się implementacja procesu roboczego , której można użyć w projekcie. Używa ona SQLite's 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 Kotlin, można utworzyć mały moduł KMP, który będzie obsługiwać proces roboczy.

Zobacz ten projekt GitHub pokazujący użycie lokalnego procesu roboczego w Room.

Gdy proces roboczy 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ślny proces roboczy opublikowany w NPM, co ułatwi konfigurację internetu.

Niestandardowe typy zwracane DAO

Różne integracje zwracanych typów DAO, takie jak RxJava i Paging, zostały przekształcone tak, aby używać nowego interfejsu API w Room 3.0 o nazwie konwertery zwracanych typów DAO. Funkcja konwertera typów zwracanych DAO (@DaoReturnTypeConverter) umożliwia przekształcenie wyniku funkcji DAO w typ niestandardowy zdefiniowany przez funkcję z adnotacjami. 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 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>
}

Dotychczasowe integracje zostały przeniesione do konwerterów zwracanych typów DAO:

Podobnie jak konwertery typów kolumn, konwertery zwracanych typów 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 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) funkcja wygenerowana przez Room , która wykona zapytanie i przeanalizuje jego wynik w obiekty danych.

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