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 die Schaltfläche mit dem Stern.

Neues Problem melden

Weitere Informationen finden Sie in der Dokumentation zum Issue Tracker.

Version 3.0

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 Einstiegspunkt für den Annotationsprozessor 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 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 gespiegelt haben, sowie die 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 Coroutines First

Um die Bibliothek besser weiterentwickeln zu können, wird in Room 3.0 nur Kotlin-Code generiert und es wird nur ein Kotlin Symbol Processor (KSP) verwendet. Im Vergleich zu Room 2.x gibt es in Room 3.0 keine Generierung von Java-Code und die Konfiguration des Annotationsprozessors ü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 des Codes 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.

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

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 (mit dem Zusatz SQLiteConnection.executeSQL) hinzugefügt. 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.

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
}

Die WebWorkerSQLiteDriver ist eine Implementierung einer SQLiteDriver, die mit einem Web Worker kommuniziert, um Datenbankvorgänge außerhalb des Hauptthreads auszuführen. Außerdem kann die Datenbank im Origin Private File System (OPFS) gespeichert werden. 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. Dabei wird SQLite-WASM verwendet und die Datenbank wird im OPFS gespeichert. 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 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.