Room-Datenbank für KMP einrichten

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:

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 mit immediateTransaction. 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.setQueryCallback
  • RoomDatabase.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.createFromAsset
  • RoomDatabase.Builder.createFromFile
  • RoomDatabase.Builder.createFromInputStream
  • RoomDatabase.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.