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-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 zugehörigen Back-Ends (kotlinc, KSP) so konfiguriert, dass Schemadateien in Ordnern mit Variantenbezeichnungen 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-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)
• Room-Paging-Ziele:js, wasmJs, tvOS und watchOS wurden als Ziele zu room3-paging hinzugefügt. (Icffd3, b/432783733)

API-Änderungen

• Multiplattform clearAllTables(): clearAllTables() wurde vereinheitlicht und ist jetzt auf allen Plattformen verfügbar. Außerdem wurde es in eine suspend-Funktion umgewandelt. (I434ae, b/322846465)
• Destruktive Migration:Den APIs fallbackToDestructiveMigration wurde ein Standardparameterwert für dropAllTables hinzugefügt. (Ica88b, b/438041176)

• Experimentelle API-Änderungen :

  1. @ExperimentalRoomApi wurde nach room-common verschoben, damit auf Annotationen 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)

Diverse Fehlerkorrekturen

• Paging-Quelle:PagingSourceDaoReturnTypeConverter wurde aktualisiert, um korrekt anzugeben, dass die zugehörige Konvertierungsfunktion 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 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 Room-Annotation-Prozessor.
• 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 auch für Room 3.0 relevant.

Die wichtigsten Unterschiede zwischen Room 2.x sind folgende:

• 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 Änderungen, die die Kompatibilität beeinträchtigen, 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 eine neue Maven-Gruppe und neue Artefakt-IDs hat. So wurde beispielsweise aus androidx.room:room-runtime 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. 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 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 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 im Vordergrund

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-Prozessors ü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 geschrieben 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 suspendierend sein, 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 suspendierende 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 über die API createFlow() im InvalidationTracker erstellt werden können.

Verwendungsbeispiele:

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 hatten, jetzt suspendierende 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 kann ein Projekt, das nicht auf das Web ausgerichtet ist, weiterhin die synchronen APIs (SQLiteDriver.open(), SQLiteConnection.prepare() und SQLiteStatement.step()) in gemeinsamem Code verwenden. Ein Projekt, das nur auf das Web ausgerichtet ist, muss hingegen die asynchronen APIs (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() und SQLiteStatement.stepAsync()) verwenden.

Zur Vereinfachung wurden dem Paket androidx.sqlite auch suspendierende 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. Diese APIs werden von der Room-Laufzeit verwendet und ermöglichen die Verwendung von Treibern in gemeinsamem Code für alle unterstützten Plattformen.

Verwendungsbeispiele:

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 Sie in Ihrem Projekt verwenden können. 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 der Konfiguration für andere 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 Einrichtung für das Web einfacher wird.

Benutzerdefinierte DAO-Rückgabetypen

Verschiedene DAO-Rückgabetyp-Integrationen wie die für RxJava und Paging wurden so umgestellt, 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 zu DAO-Rückgabetyp-Konvertern verschoben:

Wie Spaltentyp-Konverter 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 in der Abfrage verwendeten Tabellen . 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.