Room 3.0

Abhängigkeiten deklarieren

Wenn Sie eine Abhängigkeit von Room3 hinzufügen möchten, 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-Schnellstartdokumentation.

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 werden, um reproduzierbare und cachefähige Builds zu ermöglichen.

Um das Plug-in hinzuzufügen, 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 schemaDirectory festlegen. Dadurch werden der Room-Compiler und die verschiedenen Kompilierungsaufgaben und ihre Backends (kotlinc, KSP) so konfiguriert, dass Schemadateien in Ordner mit dem jeweiligen Build-Variantennamen 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-alpha05

19. Mai 2026

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

API-Änderungen

• Aktualisiert @Relation und @Junction so, dass die Properties parentColumns und entityColumns ein Array von Spaltennamen sind, die als Schlüssel zum Auflösen von Beziehungen verwendet werden. Dadurch werden zusammengesetzte Beziehungsschlüssel unterstützt. (I92196, b/64247765)

Version 3.0.0-alpha04

6. Mai 2026

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

API-Änderungen

• Fügen Sie APIs hinzu, um den Verbindungspool von Room zu konfigurieren. 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)
• Entfernen Sie DatabaseConfiguration von Room aus der öffentlichen API, da keine andere öffentliche API auf die Konfiguration verwiesen hat. (I5f1e9, b/438041176)

Fehlerkorrekturen

• Webziele sollten auf einen einzelnen Verbindungspool beschränkt werden, um Probleme mit gesperrten Datenbanken zu vermeiden, die bei OPFS auftreten (b/496255935).
• Es wird (erneut) versucht, den Fehler „Methode zu groß“ zu beheben, der auftritt, weil Room ein zu großes onValidateSchema generiert. Die Funktion wird basierend auf der Anzahl der Aussagen aufgeteilt, die Messung ist jedoch nicht präzise. Wenn dieser Fehler weiterhin auftritt, können Sie die Anzahl der Anweisungen anpassen, die Room für einen Split 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

8. April 2026

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

API-Änderungen

• Machen Sie den Konstruktor ohne Argumente von RoomDatabase öffentlich, um eine Lint-Warnung zu vermeiden, wenn auf den Konstruktor in der @Database-Deklaration verwiesen wird. (I9bac2, b/494722261)
• Fügen Sie eine Version von Room.inMemoryDatabaseBuilder und Room.databaseBuilder hinzu, die keinen Android-Kontext erfordert. Der Bedarf an einem Kontext wurde in Room 3.0 erheblich reduziert. Daher ist er ein optionaler Wert für den Builder, sodass In-Memory-Datenbanken im gemeinsamen Code einfacher erstellt werden können. (I5d502, b/438041176)

Fehlerkorrekturen

• Ein Fehler vom Typ „Code zu groß“ wurde behoben, der bei JVM- und Android-generiertem Code auftrat, wenn der Hauptteil der Funktion onValidateSchema zu groß war (b/493708172).

Version 3.0.0-alpha02

25. März 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 wurde ü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)
• Ziele für das Paging von Räumen:Die Ziele js, wasmJs, tvOS und watchOS wurden zu room3-paging hinzugefügt. (Icffd3, b/432783733)

API-Änderungen

• Multiplattform-clearAllTables():Die clearAllTables() wurde vereinheitlicht und ist jetzt auf allen Plattformen verfügbar. Sie wurde auch in eine suspend-Funktion umgewandelt. (I434ae, b/322846465)
• Destruktive Migration:Der dropAllTables-Funktion in den fallbackToDestructiveMigration-APIs wurde ein Standardparameterwert hinzugefügt. (Ica88b, b/438041176)

• Änderungen an experimentellen APIs:

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

  2. Es wurde 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)

Fehlerkorrekturen

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

Version 3.0.0-alpha01

11. März 2026

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

Room 3.0 (Paket androidx.room3) ist ein wichtiges Versionsupdate des Room 2.x-Pakets (androidx.room), das sich auf Kotlin Multiplatform (KMP) konzentriert.

Die Annotation-Kern-APIs und die Hauptkomponenten bleiben unverändert:

• Eine abstrakte Klasse, die androidx.room3.RoomDatabase erweitert und mit @Database annotiert ist, ist der Annotation Processor für 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 ein RoomDatabase.Builder abgerufen werden, das auch zum Konfigurieren der Datenbank verwendet wird.

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

Die wichtigsten Unterschiede zu 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 Version 2.x neue Funktionen:

• Unterstützung von JS und WasmJS
• 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, dass es auch eine neue Maven-Gruppe und neue Artefakt-IDs hat. Beispiel: androidx.room:room-runtime ist jetzt androidx.room3:room3-runtime und Klassen wie androidx.room.RoomDatabase befinden sich jetzt unter androidx.room3.RoomDatabase.

Keine SupportSQLite-APIs

Room 3.0 basiert vollständig auf den SQLiteDriver-APIs 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. Für die Erstellung eines RoomDatabase ist jetzt ein SQLiteDriver erforderlich.

Beispielsweise werden APIs für direkte Datenbankvorgänge durch Treiberäquivalente 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 mit SQLiteConnection als Argument ersetzt. Dazu gehören Migrations-Callback-Funktionen wie Migration.onMigrate() und AutoMigrationSpec.onPostMigrate() sowie Datenbank-Callbacks wie RoomDatabase.Callback.onCreate() und RoomDatabase.Callback.onOpen().

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

SupportSQLite-Wrapper

In Room 3.x wird der in Version 2.x erstellte SupportSQLite-Wrapper beibehalten, um die Migration zu vereinfachen. Er befindet sich jetzt in einem neuen Artefakt androidx.room3:room3-sqlite-wrapper. Mit der Compatibility API können Sie ein RoomDatabase in ein SupportSQLiteDatabase umwandeln. Aufrufe von roomDatabase.openHelper.writableDatabase können durch roomDatabase.getSupportWrapper() ersetzt werden.

Kotlin und Coroutinen im Fokus

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 in Room 3.0 keine Generierung von Java-Code und die Konfiguration des Annotation Processors über KAPT oder JavaAP ist nicht mehr möglich. KSP kann Java-Quellen verarbeiten und der Room-Compiler generiert Code für Datenbanken, Entitäten oder DAOs, deren Quelldeklarationen in Java sind. Es wird empfohlen, ein Projekt mit mehreren Modulen zu haben, 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.

Für Room 3.0 sind auch Coroutines erforderlich. Insbesondere müssen DAO-Funktionen ausgesetzt werden, es sei denn, sie geben einen reaktiven Typ wie Flow oder einen benutzerdefinierten DAO-Rückgabetyp zurück. Room-APIs zum Ausführen von Datenbankvorgängen sind auch suspend-Funktionen wie RoomDatabase.useReaderConnection und RoomDatabase.useWriterConnection.

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

Die InvalidationTracker APIs in Room 3.0 basieren auf Flow. InvalidationTracker.Observer wird zusammen mit den zugehörigen APIs addObserver und removeObserver entfernt. Der Mechanismus zum Reagieren auf Datenbankvorgänge erfolgt über Coroutine-Flows, die über die createFlow() API in der 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)
    }
}

Web-Support

Mit Room 3.0 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() und PooledConnection.usePrepared(). In den Treiber-APIs sind die asynchronen APIs auf allen Plattformen üblich und die synchronen für Nicht-Web-Ziele. Daher kann in einem Projekt, das nicht auf das Web ausgerichtet ist, weiterhin der gemeinsame Code für die synchronen APIs (SQLiteDriver.open(), SQLiteConnection.prepare() und SQLiteStatement.step()) verwendet werden. Ein Projekt, das nur auf das Web ausgerichtet ist, muss die asynchronen APIs (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() und SQLiteStatement.stepAsync()) verwenden.

Zur Vereinfachung wurden dem androidx.sqlite-Paket auch Suspend-Erweiterungsfunktionen mit den synchronen Namen der genannten APIs hinzugefügt (mit dem Zusatz 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 Laufzeit von Room verwendet werden und die Verwendung von Treibern in gemeinsamem Code für alle unterstützten Plattformen ermöglichen.

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
}

Die WebWorkerSQLiteDriver ist eine Implementierung von SQLiteDriver, die 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 WebWorkerSQLiteDriver nicht mit einem Standard-Worker ausgeliefert, der das Kommunikationsprotokoll implementiert. Die androidx-Codebasis enthält jedoch eine Worker-Implementierung, die Sie in Ihrem Projekt verwenden können. Es verwendet SQLite-WASM und speichert die Datenbank im OPFS. Der Beispiel-Worker wird als lokales NPM-Paket veröffentlicht. Dank Kotlin-Unterstützung für NPM-Abhängigkeiten kann ein kleines KMP-Modul erstellt werden, um den Worker bereitzustellen.

Dieses GitHub-Projekt zeigt die Verwendung eines lokalen Web-Workers für Room.

Sobald ein Worker im Projekt eingerichtet ist, ähnelt die Konfiguration von Room für das Web der anderer 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 für RxJava und Paging wurden so umgestellt, dass sie eine neue API in Room 3.0 namens DAO-Rückgabetyp-Konverter verwenden. Mit einer DAO-Rückgabetyp-Konverterfunktion (@DaoReturnTypeConverter) kann das Ergebnis einer DAO-Funktion in einen benutzerdefinierten Typ umgewandelt werden, der durch die annotierte Funktion definiert wird. Mit diesen Funktionen können Sie am generierten Code von Room teilnehmen, der Abfrageergebnisse in Datenobjekte umwandelt. Klassen, die DAO-Rückgabetypkonverter enthalten, müssen über die @DaoReturnTypeConverters-Annotationen in den @Database- oder @Dao-Deklarationen registriert werden.

Damit eine DAO-Abfrage beispielsweise PagingSource zurückgibt, muss die Konverterklasse in androidx.room3:room3-paging jetzt registriert werden:

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

Vorhandene Integrationen wurden in DAO-Rückgabetypkonverter verschoben:

Wie Spaltentypkonverter können auch DAO-Rückgabetypkonverter von der Anwendung definiert werden. Eine Anwendung kann beispielsweise ein @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 oben genannten Konverter können DAO-Abfragefunktionen 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 und der Typen der Parameter. 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 in der Abfrage aufgerufenen Tabellen. Dies ist nützlich, um beobachtbare / reaktive Typen zu unterstützen, wenn sie mit der InvalidationTracker.createFlow()-API von Room kombiniert werden.
• 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.