Room 3.0

Abhängigkeiten deklarieren

Für eine Abhängigkeit von Room3 müssen Sie Ihrem Projekt das Google Maven-Repository hinzufügen. Weitere Informationen finden Sie im Maven-Repository von Google.

Fügen Sie der Datei build.gradle für Ihre App oder Ihr Modul die Abhängigkeiten für die benötigten Artefakte hinzu:

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

Informationen zur Verwendung des KSP-Plug-ins finden Sie in der KSP-Schnellstartanleitung.

Weitere Informationen zu Abhängigkeiten finden Sie unter Build-Abhängigkeiten hinzufügen.

Room Gradle-Plug-in verwenden

Mit dem Room Gradle-Plug-in können Sie Optionen für den Room-Compiler konfigurieren. Das Plug-in konfiguriert das Projekt so, dass generierte Schemas (die eine Ausgabe der Kompilierungsaufgaben sind und für automatische Migrationen verwendet werden) korrekt konfiguriert sind, um reproduzierbare und cachefähige Builds zu ermöglichen.

Wenn Sie das Plug-in hinzufügen möchten, definieren Sie es und seine Version in der Gradle-Build-Datei auf oberster Ebene.

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

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

Wenden Sie das Plug-in in der Gradle-Build-Datei auf Modulebene an und verwenden Sie die Erweiterung room3.

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

plugins {
    id("androidx.room3")
}

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

Wenn Sie das Room Gradle-Plug-in verwenden, müssen Sie ein schemaDirectory festlegen. Dadurch werden der Room-Compiler und die verschiedenen Kompilierungsaufgaben sowie die Back-Ends (kotlinc, KSP) so konfiguriert, dass Schemadateien in Ordnern mit dem Namen des Flavors ausgegeben werden, z. B. schemas/flavorOneDebug/com.package.MyDatabase/1.json. Diese Dateien sollten in das Repository eingecheckt werden, damit sie für die Validierung und automatische Migrationen verwendet werden können.

Feedback

Ihr Feedback hilft uns, Jetpack zu verbessern. Wenn Sie neue Probleme entdecken oder Ideen zur Verbesserung dieser Bibliothek haben, lassen Sie es uns wissen. Bevor Sie ein neues Problem erstellen, sollten Sie sich jedoch die bereits gemeldeten Probleme in dieser Bibliothek ansehen. Wenn Sie sich einer Problemmeldung anschließen möchten, klicken Sie auf den Button mit dem Stern.

Neues Problem melden

Weitere Informationen finden Sie in der Dokumentation zum Issue Tracker.

Version 3.0

Version 3.0.0-alpha04

06.05.2026

androidx.room3:room3-*:3.0.0-alpha04 ist veröffentlicht. Version 3.0.0-alpha04 enthält diese Commits.

API-Änderungen

• APIs zum Konfigurieren des Verbindungspools von Room hinzufügen. Mit den Builder-Funktionen setSingleConnectionPool() und setMultipleConnectionPool() kann die maximale Anzahl von Verbindungen gesteuert werden, die Room zur Datenbank öffnet. (I9700d, b/438041176, b/432820350)
• DatabaseConfiguration von Room aus der öffentlichen API entfernen, da keine andere öffentliche API auf die Konfiguration verwiesen hat. (I5f1e9, b/438041176)

Diverse Fehlerkorrekturen

• Webziele auf einen einzelnen Verbindungspool beschränken, um Probleme mit gesperrten Datenbanken zu vermeiden, die bei OPFS auftreten (b/496255935).
• Erneut versuchen, den Fehler „Methode zu groß“ zu beheben, der auftritt, weil Room eine zu große onValidateSchema-Funktion generiert. Die Funktion wird basierend auf der Anzahl der Anweisungen aufgeteilt, aber die Messung ist nicht genau. Wenn dieser Fehler weiterhin auftritt, können Sie die Anzahl der Anweisungen anpassen, die Room für eine Aufteilung berücksichtigt. Verwenden Sie dazu die Option room.validationSplitSize des Annotation Processors. Der Standardwert ist derzeit auf 300 Anweisungen festgelegt. Verwenden Sie daher eine niedrigere Zahl, wenn das Problem weiterhin besteht (b/493708172).

Version 3.0.0-alpha03

08.04.2026

androidx.room3:room3-*:3.0.0-alpha03 ist veröffentlicht. Version 3.0.0-alpha03 enthält diese Commits.

API-Änderungen

• Den Konstruktor ohne Argumente von RoomDatabase öffentlich machen, um eine Lint-Warnung zu vermeiden, wenn in der Deklaration ` @Database` auf den Konstruktor verwiesen wird. (I9bac2, b/494722261)
• Eine Version von Room.inMemoryDatabaseBuilder und Room.databaseBuilder hinzufügen, die keinen Android-Kontext erfordert. Die Notwendigkeit eines Kontexts wurde in Room 3.0 erheblich reduziert. Wenn Sie ihn daher als optionalen Wert für den Builder festlegen, können Sie In-Memory-Datenbanken einfacher in gemeinsamem Code erstellen. (I5d502, b/438041176)

Diverse Fehlerkorrekturen

• Den Fehler „Code zu groß“ im JVM- und Android-generierten Code beheben, wenn der Textkörper der onValidateSchema Funktion zu groß war (b/493708172).

Version 3.0.0-alpha02

25.03.2026

androidx.room3:room3-*:3.0.0-alpha02 ist veröffentlicht. Version 3.0.0-alpha02 enthält diese Commits.

Neue Funktionen

• FTS5-Unterstützung:FTS5-Unterstützung über die Annotation @Fts5 zu Room hinzugefügt. Dazu gehören neue Konstanten für FTS5-Tokenizer (TOKENIZER_ASCII und TOKENIZER_TRIGRAM) und ein Enum für die FTS-Option „detail“ (FULL, COLUMN, und NONE). (I90934, b/146824830)
• Room-Paging-Ziele:Die Ziele js, wasmJs, tvOS und watchOS zu room3-paging hinzugefügt. (Icffd3, b/432783733)

API-Änderungen

• Multiplattform clearAllTables(): clearAllTables() verallgemeinert und auf allen Plattformen verfügbar gemacht. Außerdem wurde sie in eine suspend-Funktion umgewandelt. (I434ae, b/322846465)
• Destruktive Migration:Der Funktion dropAllTables in den APIs fallbackToDestructiveMigration einen Standardparameterwert hinzugefügt. (Ica88b, b/438041176)

• Experimentelle API-Änderungen :

  1. @ExperimentalRoomApi nach room-common verschoben, damit auf Annotationen basierende APIs als experimentell gekennzeichnet werden können.

  2. Eine experimentelle RoomWarning hinzugefügt, um die Anforderung für @ConstructedBy in einer Room-Datenbankdeklaration zu unterdrücken. In diesem Fall wird DatabaseConstructor nicht generiert und eine Factory-Implementierung muss über DatabaseBuilder bereitgestellt werden. (If5443)

Diverse Fehlerkorrekturen

• Paging-Quelle:PagingSourceDaoReturnTypeConverter aktualisiert, um korrekt anzugeben, dass die Konvertierungsfunktion für READ-Abfragen vorgesehen ist. (I3b067, b/139872302)

Version 3.0.0-alpha01

11.03.2026

androidx.room3:room3-*:3.0.0-alpha01 ist veröffentlicht.

Room 3.0 (Paket androidx.room3) ist eine wichtige Hauptversion des Room 2.x Pakets (androidx.room), die sich auf Kotlin Multiplatform (KMP) konzentriert.

Die wichtigsten Annotation-APIs und die Hauptkomponenten bleiben gleich:

• Eine abstrakte Klasse, die androidx.room3.RoomDatabase erweitert und mit @Database annotiert ist, ist der Einstiegspunkt für den Annotation Processor von Room.
• Die Datenbankdeklaration enthält eine oder mehrere Datenklassen, die das Datenbankschema beschreiben und mit @Entity annotiert sind.
• Datenbankvorgänge werden in @Dao-Deklarationen definiert, die Abfragefunktionen enthalten, deren SQL-Anweisungen über die Annotation @Query definiert werden.
• Zur Laufzeit kann die Datenbankimplementierung über einen RoomDatabase.Builder abgerufen werden, der auch zum Konfigurieren der Datenbank verwendet wird.

Die meisten Informationen im Leitfaden Daten in einer lokalen Datenbank mit Room speichern sind weiterhin für Room 3.0 relevant.

Die wichtigsten Unterschiede zwischen Room 2.x sind:

• Neues Paket: androidx.room3
• SupportSQLite-APIs werden nicht mehr unterstützt, es sei denn, Sie verwenden androidx.room3:room3-sqlite-wrapper.
• Alle Datenbankvorgänge basieren jetzt auf Coroutine-APIs.
• Nur Kotlin-Codegenerierung
• Kotlin Symbol Processing (KSP) ist erforderlich.

Neben den vorzeitigen Änderungen bietet Room 3.0 im Vergleich zu 2.x auch neue Funktionen:

• JS- und WasmJS-Unterstützung
• Benutzerdefinierte DAO-Rückgabetypen

Neues Paket

Um Kompatibilitätsprobleme mit vorhandenen Room 2.x-Implementierungen und Bibliotheken mit transitiven Abhängigkeiten von Room (z. B. WorkManager) zu vermeiden, befindet sich Room 3.0 in einem neuen Paket. Das bedeutet auch, dass es neue Maven-Gruppen- und Artefakt-IDs hat. Beispielsweise wurde androidx.room:room-runtime zu androidx.room3:room3-runtime und Klassen wie androidx.room.RoomDatabase befinden sich jetzt unter androidx.room3.RoomDatabase.

Keine SupportSQLite-APIs

Room 3.0 wird vollständig von den SQLiteDriver APIs unterstützt und verweist nicht mehr auf SupportSQLite Typen wie SupportSQLiteDatabase oder Android-Typen wie Cursor. Dies ist die wichtigste Änderung zwischen Room 3.0 und 2.x, da die RoomDatabase-APIs, die SupportSQLiteDatabase spiegelten, zusammen mit der API zum Abrufen eines SupportSQLiteOpenHelper entfernt wurden. Zum Erstellen einer RoomDatabase ist jetzt ein SQLiteDriver erforderlich.

Beispielsweise werden APIs für direkte Datenbankvorgänge durch entsprechende Treiber ersetzt:

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

Callback-APIs, die SupportSQLiteDatabase als Argument hatten, wurden ebenfalls durch die entsprechende API ersetzt, die SQLiteConnection als Argument hat. Dazu gehören Migration-Callback-Funktionen wie Migration.onMigrate() und AutoMigrationSpec.onPostMigrate() sowie Datenbank-Callbacks wie RoomDatabase.Callback.onCreate(), RoomDatabase.Callback.onOpen() usw.

Wenn Room in einem KMP-Projekt verwendet wurde, ist die Migration zu 3.0 ist einfacher, da hauptsächlich Importverweise aktualisiert werden müssen. Andernfalls gilt dieselbe Migrationsstrategie von Room in Android-only zu KMP. Weitere Informationen finden Sie im Room KMP Migrationsleitfaden.

SupportSQLite-Wrapper

Room 3.x behält den in 2.x erstellten SupportSQLite-Wrapper bei, um Migrationen zu erleichtern. Er befindet sich jetzt in einem neuen Artefakt: androidx.room3:room3-sqlite-wrapper. Mit der Kompatibilitäts-API können Sie eine RoomDatabase in eine SupportSQLiteDatabase konvertieren. Aufrufe von roomDatabase.openHelper.writableDatabase können durch roomDatabase.getSupportWrapper() ersetzt werden.

Kotlin und Coroutines zuerst

Um die Bibliothek besser weiterentwickeln zu können, generiert Room 3.0 nur Kotlin-Code und ist nur ein Kotlin Symbol Processor (KSP). Im Vergleich zu Room 2.x gibt es keine Java-Codegenerierung und die Konfiguration des Annotation Processors über KAPT oder JavaAP ist in Room 3.0 nicht mehr möglich. KSP kann Java-Quellen verarbeiten und der Room-Compiler generiert Code für Datenbanken, Entitäten oder DAOs, deren Quellendeklarationen in Java sind. Es wird empfohlen, ein Projekt mit mehreren Modulen zu verwenden, in dem die Room-Nutzung konzentriert ist und das Kotlin Gradle-Plug-in und KSP angewendet werden können, ohne den Rest der Codebasis zu beeinträchtigen.

Room 3.0 erfordert auch die Verwendung von Coroutines. Insbesondere müssen DAO-Funktionen suspendiert werden, es sei denn, sie geben einen reaktiven Typ zurück, z. B. einen Flow oder einen benutzerdefinierten DAO-Rückgabetyp. Room-APIs zum Ausführen von Datenbankvorgängen sind ebenfalls suspend-Funktionen, z. B. RoomDatabase.useReaderConnection und RoomDatabase.useWriterConnection.

Im Gegensatz zu Room 2.x ist es nicht mehr möglich, eine RoomDatabase mit einem Executor zu konfigurieren. Stattdessen kann über den Builder der Datenbank ein CoroutineContext zusammen mit einem Dispatcher bereitgestellt werden.

InvalidationTracker-APIs in Room 3.0 basieren auf Flow. InvalidationTracker.Observer wurde zusammen mit den zugehörigen APIs addObserver und removeObserver entfernt. Der Mechanismus zum Reagieren auf Datenbankvorgänge erfolgt über Coroutine-Flows, die mit der API createFlow() im InvalidationTracker erstellt werden können.

Nutzungsbeispiel:

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

Webunterstützung

Mit der Version 3.0 von Room werden JavaScript und WasmJs als KMP-Ziele hinzugefügt. In Kombination mit der Veröffentlichung der SQLiteDriver-Schnittstellen (androidx.sqlite:sqlite), die auch auf JavaScript und WasmJs ausgerichtet sind, und einem neuen Treiber WebWorkerSQLiteDriver im neuen Artefakt androidx.sqlite:sqlite-web ist es möglich, Room in gemeinsamem Code zu verwenden, der auf alle wichtigen KMP-Plattformen ausgerichtet ist.

Aufgrund der asynchronen Natur der Webplattformen sind Room-APIs, die SQLiteStatement als Argument verwendet haben, jetzt suspend-Funktionen. Beispiele für diese Funktionen sind Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() und andere. In den Treiber-APIs sind die asynchronen APIs auf allen Plattformen üblich und die synchronen APIs für Nicht-Web-Ziele. Daher können Projekte, die nicht auf das Web ausgerichtet sind, weiterhin die synchronen APIs (SQLiteDriver.open(), SQLiteConnection.prepare() und SQLiteStatement.step()) in gemeinsamem Code verwenden. Projekte, die nur auf das Web ausgerichtet sind, müssen die asynchronen APIs (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() und SQLiteStatement.stepAsync()) verwenden.

Zur Vereinfachung wurden dem Paket androidx.sqlite auch suspend-Erweiterungsfunktionen mit den synchronen Namen der genannten APIs hinzugefügt (mit Ausnahme von SQLiteConnection.executeSQL). Diese APIs werden empfohlen, wenn das Projekt sowohl auf Web- als auch auf Nicht-Web-Plattformen ausgerichtet ist, da die APIs expect-/actual-Deklarationen sind, die je nach Plattform die richtige Variante aufrufen. Dies sind die APIs, die von der Room-Laufzeit verwendet werden, und sie ermöglichen die Verwendung von Treibern in gemeinsamem Code für alle unterstützten Plattformen.

Nutzungsbeispiel:

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
}

Der WebWorkerSQLiteDriver ist eine Implementierung eines SQLiteDriver, der mit einem Web Worker kommuniziert, um Datenbankvorgänge außerhalb des Hauptthreads auszuführen und die Datenbank im Origin Private File System (OPFS) zu speichern. Zum Instanziieren des Treibers ist ein Worker erforderlich, der ein einfaches Kommunikationsprotokoll implementiert. Das Protokoll wird im WebWorkerSQLiteDriver KDoc beschrieben.

Derzeit wird der WebWorkerSQLiteDriver nicht mit einem Standard-Worker ausgeliefert, der das Kommunikationsprotokoll implementiert. Die AndroidX-Codebasis enthält jedoch eine Worker-Implementierung, die in Ihrem Projekt verwendet werden kann. Sie verwendet WASM von SQLite's und speichert die Datenbank in OPFS. Der Beispiel-Worker wird als lokales NPM-Paket veröffentlicht. Dank der Unterstützung von NPM-Abhängigkeiten in Kotlin, kann ein kleines KMP-Modul erstellt werden, um den Worker bereitzustellen.

In diesem GitHub-Projekt wird die Verwendung eines lokalen Web Workers für Room veranschaulicht.

Sobald ein Worker im Projekt eingerichtet ist, ähnelt die Konfiguration von Room für das Web anderen Plattformen:

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

Eine zukünftige Version des Web-Treibers enthält möglicherweise einen Standard-Worker, der in NPM veröffentlicht wird, wodurch die Web-Einrichtung einfacher wird.

Benutzerdefinierte DAO-Rückgabetypen

Verschiedene DAO-Rückgabetyp-Integrationen wie die für RxJava und Paging wurden so umgewandelt, dass sie eine neue API in Room 3.0 verwenden, die als DAO-Rückgabetyp-Konverter bezeichnet wird. Mit einer DAO-Rückgabetyp-Konverterfunktion (@DaoReturnTypeConverter) kann das Ergebnis einer DAO-Funktion in einen benutzerdefinierten Typ umgewandelt werden, der von der annotierten Funktion definiert wird. Mit diesen Funktionen können Sie am generierten Code von Room teilnehmen, der Abfrageergebnisse in Datenobjekte umwandelt. Klassen, die DAO-Rückgabetyp-Konverter enthalten, müssen über die @DaoReturnTypeConverters Annotationen in den @Database oder @Dao Deklarationen registriert werden.

Wenn beispielsweise eine DAO-Abfrage eine PagingSource zurückgeben soll, muss die Konverterklasse in androidx.room3:room3-paging registriert werden:

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

Vorhandene Integrationen wurden in DAO-Rückgabetyp-Konverter verschoben:

Wie Spaltentypkonverter können auch DAO-Rückgabetyp-Konverter von der Anwendung definiert werden. Eine Anwendung könnte beispielsweise einen @DaoReturnTypeConverter für den Webtyp kotlin.js.Promise deklarieren.

object PromiseDaoReturnTypeConverter {
    @DaoReturnTypeConverter([OperationType.READ, OperationType.WRITE])
    fun <T> convert(
        db: RoomDatabase,
        executeAndConvert: suspend () -> T
    ): Promise<T> {
        return db.getCoroutineScope().promise { executeAndConvert() }
    }
}

Mit dem obigen Konverter können DAO-Abfragefunktionen dann Promise zurückgeben:

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

Für eine @DaoReturnTypeConverter-Funktion gelten einige Anforderungen hinsichtlich der Anzahl der Parameter und ihrer Typen. Folgende Parameter sind möglich:

• db: RoomDatabase: (Optional) Bietet Zugriff auf die RoomDatabase Instanz, was für zusätzliche Datenbankvorgänge oder den Zugriff auf den Coroutine-Bereich nützlich sein kann.
• tableNames: Array<String>: (Optional) Enthält die aufgerufenen Tabellen der Abfrage. Dies ist nützlich für die Unterstützung von beobachtbaren / reaktiven Typen in Kombination mit der API InvalidationTracker.createFlow() von Room.
• rawQuery: RoomRawQuery: (Optional) Enthält zur Laufzeit eine Instanz der Abfrage, die Transformationen wie die von PagingSourceDaoReturnTypeConverter implementierte LIMIT / OFFSET-Strategie ermöglicht.
• executeAndConvert: suspend () -> T: (Erforderlich) Die von Room generierte Funktion, die die Abfrage ausführt und das Ergebnis in Datenobjekte parst.

Weitere Informationen zu den Anforderungen für das Erstellen eines DAO-Rückgabetyp Konverters finden Sie im KDoc zur @DaoReturnTypeConverter API.