Die Room-Persistenzbibliothek bietet eine Abstraktionsebene über SQLite, um einen robusteren Datenbankzugriff zu ermöglichen und gleichzeitig die volle Leistung von SQLite zu nutzen. Auf dieser Seite geht es um die Verwendung von Room in Kotlin Multiplatform (KMP)-Projekten. Weitere Informationen zur Verwendung von Room finden Sie unter Daten mit Room in einer lokalen Datenbank speichern oder in unseren offiziellen Beispielen.
Abhängigkeiten einrichten
Wenn Sie Room in Ihrem KMP-Projekt einrichten möchten, fügen Sie die Abhängigkeiten für die Artefakte in der Datei build.gradle.kts für Ihr KMP-Modul hinzu.
Definieren Sie die Abhängigkeiten in der Datei libs.versions.toml:
[versions]
room3 = "3.1.0-alpha03"
sqlite = "2.7.1"
ksp = "<kotlinCompatibleKspVersion>"
[libraries]
androidx-sqlite-bundled = { module = "androidx.sqlite:sqlite-bundled", version.ref = "sqlite" }
androidx-room3-runtime = { module = "androidx.room3:room3-runtime", version.ref = "room3" }
androidx-room3-compiler = { module = "androidx.room3:room3-compiler", version.ref = "room3" }
# Optional SQLite Wrapper
androidx-room3-sqlite-wrapper = { module = "androidx.room3:room3-sqlite-wrapper", version.ref = "room3" }
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
androidx-room3 = { id = "androidx.room3", version.ref = "room3" }
Fügen Sie das Room Gradle-Plug-in hinzu, um Room-Schemas und das KSP-Plug-in zu konfigurieren.
plugins {
alias(libs.plugins.ksp)
alias(libs.plugins.androidx.room3)
}
Fügen Sie die Room-Laufzeitabhängigkeit und die gebündelte SQLite-Bibliothek hinzu:
commonMain.dependencies {
implementation(libs.androidx.room3.runtime)
implementation(libs.androidx.sqlite.bundled)
}
// Optional when using Room SQLite Wrapper
androidMain.dependencies {
implementation(libs.androidx.room3.sqlite.wrapper)
}
Fügen Sie die KSP-Abhängigkeiten dem root-dependencies-Block hinzu. Sie müssen alle Ziele hinzufügen, die Ihre App verwendet. Weitere Informationen finden Sie unter KSP mit Kotlin Multiplatform.
dependencies {
add("kspAndroid", libs.androidx.room3.compiler)
add("kspIosSimulatorArm64", libs.androidx.room3.compiler)
add("kspIosX64", libs.androidx.room3.compiler)
add("kspIosArm64", libs.androidx.room3.compiler)
// Add any other platform target you use in your project, for example kspDesktop
}
Definieren Sie das Room-Schemaverzeichnis. Weitere Informationen finden Sie unter Speicherort des Schemas mit dem Room Gradle-Plug-in festlegen.
room {
schemaDirectory("$projectDir/schemas")
}
Datenbankklassen definieren
Sie müssen eine mit @Database annotierte Datenbankklasse zusammen mit DAOs und Entitäten im gemeinsamen Quellsatz Ihres freigegebenen KMP-Moduls erstellen. Wenn Sie diese Klassen in gemeinsamen Quellen platzieren, können sie auf allen Zielplattformen gemeinsam genutzt werden.
// shared/src/commonMain/kotlin/Database.kt @Database(entities = [TodoEntity::class], version = 1) @ConstructedBy(AppDatabaseConstructor::class) abstract class AppDatabase : RoomDatabase() { abstract fun getDao(): TodoDao } // The Room compiler generates the `actual` implementations. @Suppress("KotlinNoActualForExpect") expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase> { override fun initialize(): AppDatabase }
Wenn Sie ein expect-Objekt mit der RoomDatabaseConstructor-Schnittstelle deklarieren, generiert der Room-Compiler die actual-Implementierungen. In Android Studio wird möglicherweise die folgende Warnung angezeigt, die Sie mit @Suppress("KotlinNoActualForExpect") unterdrücken können:
Expected object 'AppDatabaseConstructor' has no actual declaration in module`
Definieren Sie als Nächstes entweder eine neue DAO-Schnittstelle oder verschieben Sie eine vorhandene nach commonMain:
// shared/src/commonMain/kotlin/TodoDao.kt @Dao interface TodoDao { @Insert suspend fun insert(item: TodoEntity) @Query("SELECT count(*) FROM TodoEntity") suspend fun count(): Int @Query("SELECT * FROM TodoEntity") fun getAllAsFlow(): Flow<List<TodoEntity>> }
Definieren oder verschieben Sie Ihre Entitäten nach commonMain:
// shared/src/commonMain/kotlin/TodoEntity.kt @Entity data class TodoEntity( @PrimaryKey(autoGenerate = true) val id: Long = 0, val title: String, val content: String )
Plattformspezifische Datenbank-Builder erstellen
Sie müssen einen Datenbank-Builder definieren, um Room auf jeder Plattform zu instanziieren. Dies ist der einzige Teil der API, den Sie aufgrund von Unterschieden bei den Dateisystem-APIs in plattformspezifischen Source-Sets definieren müssen.
Android
Unter Android rufen Sie den Datenbankstandort normalerweise mit der Context.getDatabasePath API ab. Geben Sie zum Erstellen der Datenbankinstanz einen Context und den Datenbankpfad an.
// shared/src/androidMain/kotlin/Database.android.kt fun getDatabaseBuilder(context: Context): RoomDatabase.Builder<AppDatabase> { val appContext = context.applicationContext val dbFile = appContext.getDatabasePath("my_room.db") return Room.databaseBuilder<AppDatabase>( context = appContext, name = dbFile.absolutePath ) }
iOS
Wenn Sie die Datenbankinstanz unter iOS erstellen möchten, geben Sie einen Datenbankpfad mit NSFileManager an, der sich normalerweise in NSDocumentDirectory befindet.
// shared/src/iosMain/kotlin/Database.ios.kt fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> { val dbFilePath = documentDirectory() + "/my_room.db" return Room.databaseBuilder<AppDatabase>( name = dbFilePath, ) } @OptIn(ExperimentalForeignApi::class) private fun documentDirectory(): String { val documentDirectory = NSFileManager.defaultManager.URLForDirectory( directory = NSDocumentDirectory, inDomain = NSUserDomainMask, appropriateForURL = null, create = false, error = null, ) return requireNotNull(documentDirectory?.path) }
JVM-Desktop
Geben Sie zum Erstellen der Datenbankinstanz einen Datenbankpfad mit Java- oder Kotlin-APIs an.
// shared/src/jvmMain/kotlin/Database.desktop.kt
fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> {
val dbFile = File(System.getProperty("java.io.tmpdir"), "my_room.db")
return Room.databaseBuilder<AppDatabase>(
name = dbFile.absolutePath,
)
}
Datenbank instanziieren
Nachdem Sie die RoomDatabase.Builder von einem der plattformspezifischen Konstruktoren erhalten haben, können Sie den Rest der Room-Datenbank im gemeinsamen Code zusammen mit der eigentlichen Datenbankinstanziierung konfigurieren.
// shared/src/commonMain/kotlin/Database.kt fun getRoomDatabase( builder: RoomDatabase.Builder<AppDatabase> ): AppDatabase { return builder .setDriver(BundledSQLiteDriver()) .setQueryCoroutineContext(Dispatchers.IO) .build() }
SQLite-Treiber auswählen
Im vorherigen Code-Snippet wird die Builder-Funktion setDriver aufgerufen, um festzulegen, welchen SQLite-Treiber die Room-Datenbank verwenden soll. Diese Treiber unterscheiden sich je nach Zielplattform. In den vorherigen Code-Snippets wird BundledSQLiteDriver verwendet.
Dies ist der empfohlene Treiber, der SQLite aus der Quelle kompiliert enthält. Er bietet die konsistenteste und aktuellste Version von SQLite auf allen Plattformen.
Wenn Sie die vom Betriebssystem bereitgestellte SQLite-Version verwenden möchten, verwenden Sie die setDriver API in den plattformspezifischen Source-Sets, die einen plattformspezifischen Treiber angeben. Eine Beschreibung der verfügbaren Treiberimplementierungen finden Sie unter Treiberimplementierungen. Sie haben folgende Möglichkeiten:
AndroidSQLiteDriverinandroidMainNativeSQLiteDriveriniosMain
Wenn Sie NativeSQLiteDriver verwenden möchten, müssen Sie die Linker-Option -lsqlite3 angeben, damit die iOS-App dynamisch mit der SQLite-Systemdatenbank verknüpft wird.
// shared/build.gradle.kts
kotlin {
listOf(
iosX64(),
iosArm64(),
iosSimulatorArm64()
).forEach { iosTarget ->
iosTarget.binaries.framework {
baseName = "TodoApp"
isStatic = true
// Required when using NativeSQLiteDriver
linkerOpts.add("-lsqlite3")
}
}
}
Koroutinenkontext festlegen
Ein RoomDatabase-Objekt unter Android kann optional mit freigegebenen Anwendungsausführern konfiguriert werden, die RoomDatabase.Builder.setQueryExecutor verwenden, um Datenbankvorgänge auszuführen.
Da Executors nicht KMP-kompatibel sind, ist die setQueryExecutor API von Room in commonMain nicht verfügbar. Stattdessen muss das RoomDatabase-Objekt mit einem CoroutineContext konfiguriert werden, das Sie mit RoomDatabase.Builder.setCoroutineContext festlegen können. Wenn Sie keinen Kontext festlegen, wird für das RoomDatabase-Objekt standardmäßig Dispatchers.IO verwendet.
Minimierung und Verschleierung
Wenn das Projekt minimiert oder verschleiert ist, müssen Sie die folgende ProGuard-Regel einfügen, damit Room die generierte Implementierung der Datenbankdefinition finden kann:
-keep class * extends androidx.room3.RoomDatabase { <init>(); }
Zu Kotlin Multiplatform migrieren
Room wurde ursprünglich als Android-Bibliothek entwickelt und später zu KMP migriert, wobei der Schwerpunkt auf der API-Kompatibilität lag. Die KMP-Version von Room unterscheidet sich etwas zwischen den Plattformen und von der Android-spezifischen Version. Diese Unterschiede werden im Folgenden aufgeführt und beschrieben.
Von Support SQLite zu SQLite Driver migrieren
Alle Verwendungen von SupportSQLiteDatabase und anderen APIs in androidx.sqlite.db müssen mit SQLite-Treiber-APIs refaktoriert werden, da die APIs in androidx.sqlite.db nur für Android verfügbar sind (beachten Sie das andere Paket als das KMP-Paket).
Aus Gründen der Abwärtskompatibilität und solange RoomDatabase mit einem SupportSQLiteOpenHelper.Factory konfiguriert ist (z. B. kein SQLiteDriver festgelegt ist), verhält sich Room im „Kompatibilitätsmodus“, in dem sowohl die Support SQLite- als auch die SQLite Driver APIs wie erwartet funktionieren. Dies ermöglicht inkrementelle Migrationen, sodass Sie nicht alle Support SQLite-Nutzungen in einer einzigen Änderung in SQLite Driver konvertieren müssen.
SQLite-Wrapper von Room verwenden
Das Artefakt androidx.room3:room3-sqlite-wrapper stellt APIs bereit, um während der Migration eine Brücke zwischen SQLiteDriver und SupportSQLiteDatabase zu schlagen.
Wenn Sie einen SupportSQLiteDatabase von einem RoomDatabase abrufen möchten, der mit einem SQLiteDriver konfiguriert ist, verwenden Sie die neue Erweiterungsfunktion RoomDatabase.getSupportWrapper. Dieser Kompatibilitäts-Wrapper hilft dabei, bestehende Verwendungen von SupportSQLiteDatabase beizubehalten, die Sie häufig von RoomDatabase.openHelper.writableDatabase erhalten, während Sie SQLiteDriver übernehmen. Dies gilt insbesondere für Codebasen mit umfangreichen SupportSQLite-API-Verwendungen, die BundledSQLiteDriver verwenden möchten.
Migrationsunterklassen konvertieren
Migrations-Unterklassen müssen zu den entsprechenden SQLite-Treibern migriert werden:
Kotlin Multiplatform
Migrationsunterklassen
object Migration_1_2 : Migration(1, 2) { override suspend fun migrate(connection: SQLiteConnection) { // ... } }
Unterklassen für die automatische Migrationsspezifikation
class AutoMigrationSpec_1_2 : AutoMigrationSpec { override suspend fun onPostMigrate(connection: SQLiteConnection) { // ... } }
Nur für Android
Migrationsunterklassen
object Migration_1_2 : Migration(1, 2) {
override fun migrate(db: SupportSQLiteDatabase) {
// …
}
}
Unterklassen für die automatische Migrationsspezifikation
class AutoMigrationSpec_1_2 : AutoMigrationSpec {
override fun onPostMigrate(db: SupportSQLiteDatabase) {
// …
}
}
Datenbank-Callback konvertieren
Datenbank-Callbacks müssen zu den entsprechenden SQLite-Treibern migriert werden:
Kotlin Multiplatform
object MyRoomCallback : RoomDatabase.Callback() { override suspend fun onCreate(connection: SQLiteConnection) { // ... } override suspend fun onDestructiveMigration(connection: SQLiteConnection) { // ... } override suspend fun onOpen(connection: SQLiteConnection) { // ... } }
Nur für Android
object MyRoomCallback : RoomDatabase.Callback() {
override fun onCreate(db: SupportSQLiteDatabase) {
// …
}
override fun onDestructiveMigration(db: SupportSQLiteDatabase) {
// …
}
override fun onOpen(db: SupportSQLiteDatabase) {
// …
}
}
@RawQuery DAO-Funktionen konvertieren
Funktionen, die mit @RawQuery annotiert sind und für Nicht-Android-Plattformen kompiliert werden, müssen einen Parameter vom Typ RoomRawQuery anstelle von SupportSQLiteQuery deklarieren.
Kotlin Multiplatform
Rohabfrage definieren
@Dao interface TodoDao { @RawQuery suspend fun getTodos(query: RoomRawQuery): List<TodoEntity> }
Ein RoomRawQuery kann dann verwendet werden, um zur Laufzeit eine Abfrage zu erstellen:
suspend fun AppDatabase.getTodosWithLowercaseTitle(title: String): List<TodoEntity> { val query = RoomRawQuery( sql = "SELECT * FROM TodoEntity WHERE title = ?", onBindStatement = { it.bindText(1, title.lowercase()) } ) return getDao().getTodos(query) }
Nur für Android
Rohabfrage definieren
@Dao
interface TodoDao {
@RawQuery
suspend fun getTodos(query: SupportSQLiteQuery): List<TodoEntity>
}
Ein SimpleSQLiteQuery kann dann verwendet werden, um zur Laufzeit eine Abfrage zu erstellen:
suspend fun AndroidOnlyDao.getTodosWithLowercaseTitle(title: String): List<TodoEntity> {
val query = SimpleSQLiteQuery(
query = "SELECT * FROM TodoEntity WHERE title = ?",
bindArgs = arrayOf(title.lowercase())
)
return getTodos(query)
}
Blockierende DAO-Funktionen konvertieren
Room profitiert von der funktionsreichen asynchronen kotlinx.coroutines-Bibliothek, die Kotlin für mehrere Plattformen bietet. Für eine optimale Funktionalität werden suspend-Funktionen für DAOs erzwungen, die in einem KMP-Projekt kompiliert wurden. Eine Ausnahme bilden DAOs, die in androidMain implementiert wurden, um die Abwärtskompatibilität mit der vorhandenen Codebasis aufrechtzuerhalten. Wenn Sie Room für KMP verwenden, müssen alle DAO-Funktionen, die für Nicht-Android-Plattformen kompiliert werden, suspend-Funktionen sein.
Kotlin Multiplatform
Abfragen werden gesperrt
@Query("SELECT * FROM Todo") suspend fun getAllTodos(): List<Todo>
Transaktionen aussetzen
@Transaction suspend fun transaction() { // ... }
Nur für Android
Blockierende Abfragen
@Query("SELECT * FROM Todo")
fun getAllTodos(): List<Todo>
Blockierende Transaktionen
@Transaction
fun blockingTransaction() { … }
Reaktive Typen in Flow konvertieren
Nicht alle DAO-Funktionen müssen „suspend“-Funktionen sein. DAO-Funktionen, die reaktive Typen wie LiveData oder Flowable von RxJava zurückgeben, sollten nicht in Sperrfunktionen umgewandelt werden. Einige Typen wie LiveData sind jedoch nicht KMP-kompatibel. DAO-Funktionen mit reaktiven Rückgabetypen müssen zu Koroutinen-Abläufen migriert werden.
Kotlin Multiplatform
Reaktive Typen Flows
@Query("SELECT * FROM Todo") fun getTodosFlow(): Flow<List<Todo>>
Nur für Android
Reaktive Typen wie LiveData oder Flowable von RxJava
@Query("SELECT * FROM Todo")
fun getTodosLiveData(): LiveData<List<Todo>>
Transaction APIs konvertieren
Datenbanktransaktions-APIs für Room KMP können zwischen Schreib- (useWriterConnection) und Lesetransaktionen (useReaderConnection) unterscheiden.
Kotlin Multiplatform
val database: RoomDatabase = getRoomDatabase(builder) database.useWriterConnection { transactor -> transactor.immediateTransaction { // perform database operations in transaction. } }
Nur für Android
val database: RoomDatabase = …
database.withTransaction {
// perform database operations in transaction
}
Schreibtransaktionen
Verwenden Sie Schreibtransaktionen, um sicherzustellen, dass mehrere Abfragen Daten atomar schreiben, damit Leser konsistent auf die Daten zugreifen können. Dazu können Sie useWriterConnection mit einem der drei Transaktionstypen verwenden:
immediateTransaction: Im WAL-Modus (Write-Ahead Logging) (Standard) erhält dieser Transaktionstyp beim Start eine Sperre, aber Leser können weiterhin lesen. Dies ist in den meisten Fällen die bevorzugte Option.deferredTransaction: Die Transaktion erhält erst mit der ersten Schreibanweisung eine Sperre. Verwenden Sie diese Art von Transaktion als Optimierung, wenn Sie sich nicht sicher sind, ob innerhalb der Transaktion ein Schreibvorgang erforderlich ist. Wenn Sie beispielsweise eine Transaktion starten, um Songs aus einer Playlist zu löschen, und nur den Namen der Playlist angeben, die Playlist aber nicht existiert, ist kein Schreibvorgang (Löschvorgang) erforderlich.exclusiveTransaction: Dieser Modus verhält sich im WAL-Modus identisch mitimmediateTransaction. In anderen Journaling-Modi wird verhindert, dass andere Datenbankverbindungen die Datenbank lesen, während die Transaktion ausgeführt wird.
Lesetransaktionen
Verwenden Sie Lesetransaktionen, um mehrmals konsistent aus der Datenbank zu lesen. Beispiel: Sie haben zwei oder mehr separate Abfragen und verwenden keine JOIN-Klausel. In Leseverbindungen sind nur verzögerte Transaktionen zulässig. Der Versuch, eine sofortige oder exklusive Transaktion in einer Leseverbindung zu starten, führt zu einer Ausnahme, da diese als Schreibvorgänge betrachtet werden.
val database: RoomDatabase = getRoomDatabase(builder) database.useReaderConnection { transactor -> transactor.deferredTransaction { // perform database operations in transaction. } }
Nicht verfügbar in Kotlin Multiplatform
Einige der APIs, die für Android verfügbar waren, sind in Kotlin Multiplatform nicht verfügbar.
Abfrage-Callback
Die folgenden APIs zum Konfigurieren von Abfrage-Callbacks sind nicht in „common“ verfügbar und daher auch nicht auf anderen Plattformen als Android.
RoomDatabase.Builder.setQueryCallbackRoomDatabase.QueryCallback
Automatisch schließende Datenbank
Die API zum Aktivieren des automatischen Schließens nach einer Zeitüberschreitung, RoomDatabase.Builder.setAutoCloseTimeout, ist nur auf Android-Geräten verfügbar.
Vorgepackte Datenbank
Die folgenden APIs zum Erstellen einer RoomDatabase mit einer vorhandenen Datenbank (einer vorkonfigurierten Datenbank) sind nicht in „common“ verfügbar und daher auch nicht auf anderen Plattformen als Android:
RoomDatabase.Builder.createFromAssetRoomDatabase.Builder.createFromFileRoomDatabase.Builder.createFromInputStreamRoomDatabase.PrepackagedDatabaseCallback
Multi-Instanz-Modus-Entwertung
Die API zum Aktivieren der Multi-Instanz-Invalidierung, RoomDatabase.Builder.enableMultiInstanceInvalidation, ist nur auf Android-Geräten verfügbar und nicht auf gängigen oder anderen Plattformen.
Empfehlungen für Sie
- Hinweis: Der Linktext wird angezeigt, wenn JavaScript deaktiviert ist.
- Codelab „Vorhandene Apps zu Room für KMP migrieren“
- Codelab „Erste Schritte mit KMP“
- Daten mit Room in einer lokalen Datenbank speichern