KMP için Room veritabanı oluşturma

Room kalıcılık kitaplığı, SQLite'ın tüm gücünden yararlanırken daha sağlam veritabanı erişimi sağlamak için SQLite üzerinde bir soyutlama katmanı sağlar. Bu sayfada, Kotlin Multiplatform (KMP) projelerinde Room'un kullanımı ele alınmaktadır. Room'u kullanma hakkında daha fazla bilgi için Room'u kullanarak verileri yerel bir veritabanına kaydetme başlıklı makaleyi veya resmi örneklerimizi inceleyin.

Bağımlılıkları ayarlama

KMP projenizde Room'u ayarlamak için KMP modülünüzün build.gradle.kts dosyasındaki yapıların bağımlılıklarını ekleyin.

libs.versions.toml dosyasında bağımlılıkları tanımlayın:

[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" }

Room şemalarını ve KSP eklentisini yapılandırmak için Room Gradle eklentisini ekleyin.

plugins {
  alias(libs.plugins.ksp)
  alias(libs.plugins.androidx.room3)
}

Room çalışma zamanı bağımlılığını ve paket halinde sunulan SQLite kitaplığını ekleyin:

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

KSP bağımlılıklarını root dependencies bloğuna ekleyin. Uygulamanızın kullandığı tüm hedefleri eklemeniz gerekir. Daha fazla bilgi için Kotlin Multiplatform ile KSP başlıklı makaleyi inceleyin.

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
}

Room şeması dizinini tanımlayın. Daha fazla bilgi için Room Gradle eklentisini kullanarak şema konumunu ayarlama başlıklı makaleyi inceleyin.

room {
    schemaDirectory("$projectDir/schemas")
}

Veritabanı sınıflarını tanımlama

Paylaşılan KMP modülünüzün ortak kaynak grubunda DAO'lar ve varlıklarla birlikte @Database ile ek açıklama eklenmiş bir veritabanı sınıfı oluşturmanız gerekir. Bu sınıfları ortak kaynaklara yerleştirmek, tüm hedef platformlarda paylaşılmalarına olanak tanır.

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

RoomDatabaseConstructor arayüzüyle bir expect nesnesi tanımladığınızda Room derleyicisi actual uygulamalarını oluşturur. Android Studio, @Suppress("KotlinNoActualForExpect") ile gizleyebileceğiniz aşağıdaki uyarıyı verebilir:

Expected object 'AppDatabaseConstructor' has no actual declaration in module`

Ardından, yeni bir DAO arayüzü tanımlayın veya mevcut bir arayüzü commonMain dizinine taşıyın:

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

Varlıklarınızı commonMain için tanımlayın veya bu düzeye taşıyın:

// shared/src/commonMain/kotlin/TodoEntity.kt

@Entity
data class TodoEntity(
    @PrimaryKey(autoGenerate = true) val id: Long = 0,
    val title: String,
    val content: String
)

Platforma özel veritabanı oluşturucular oluşturma

Room'u her platformda örneklendirmek için bir veritabanı oluşturucu tanımlamanız gerekir. Dosya sistemi API'lerindeki farklılıklar nedeniyle API'nin platforma özgü kaynak gruplarında tanımlamanız gereken tek kısmı budur.

Android

Android'de veritabanı konumunu genellikle Context.getDatabasePath API'sini kullanarak alırsınız. Veritabanı örneğini oluşturmak için bir Context ve veritabanı yolunu belirtin.

// 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

iOS'te veritabanı örneğini oluşturmak için genellikle NSDocumentDirectory içinde bulunan NSFileManager kullanarak bir veritabanı yolu sağlayın.

// 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 masaüstü

Veritabanı örneğini oluşturmak için Java veya Kotlin API'lerini kullanarak bir veritabanı yolu sağlayın.

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

Veritabanını örneklendirme

Platforma özel kuruculardan birinden RoomDatabase.Builder değerini aldıktan sonra, Room veritabanının geri kalanını ortak kodda gerçek veritabanı örneklendirmesiyle birlikte yapılandırabilirsiniz.

// shared/src/commonMain/kotlin/Database.kt

fun getRoomDatabase(
    builder: RoomDatabase.Builder<AppDatabase>
): AppDatabase {
    return builder
        .setDriver(BundledSQLiteDriver())
        .setQueryCoroutineContext(Dispatchers.IO)
        .build()
}

SQLite sürücüsü seçme

Önceki kod snippet'i, Room veritabanının hangi SQLite sürücüsünü kullanması gerektiğini tanımlamak için setDriver oluşturucu işlevini çağırır. Bu etkenler, hedef platforma göre farklılık gösterir. Önceki kod snippet'leri BundledSQLiteDriver kullanır. Kaynaktan derlenmiş SQLite'ı içeren önerilen sürücüdür. Bu sürücü, tüm platformlarda SQLite'ın en tutarlı ve güncel sürümünü sağlar.

İşletim sisteminin sağladığı SQLite'ı kullanmak istiyorsanız platforma özgü sürücüyü belirten platforma özgü kaynak gruplarında setDriver API'sini kullanın. Kullanılabilir sürücü uygulamalarının açıklamaları için Sürücü uygulamaları bölümüne bakın. Aşağıdakilerden birini kullanabilirsiniz:

NativeSQLiteDriver kullanmak için iOS uygulamasının sistem SQLite'ına dinamik olarak bağlanması amacıyla bir bağlayıcı seçeneği (-lsqlite3) sağlamanız gerekir.

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

Eş yordam bağlamı ayarlama

Android'deki bir RoomDatabase nesnesi, veritabanı işlemlerini gerçekleştirmek için isteğe bağlı olarak RoomDatabase.Builder.setQueryExecutor kullanılarak paylaşılan uygulama yürütücülerle yapılandırılabilir.

Yürütücüler KMP ile uyumlu olmadığından Room'un setQueryExecutor API'si commonMain içinde kullanılamaz. Bunun yerine RoomDatabase nesnesi, RoomDatabase.Builder.setCoroutineContext kullanarak ayarlayabileceğiniz bir CoroutineContext ile yapılandırılmalıdır. Bağlam ayarlamazsanız RoomDatabase nesnesi varsayılan olarak Dispatchers.IO olur.

Sadeleştirme ve kod karartma

Proje küçültülmüş veya gizlenmişse Room'un veritabanı tanımının oluşturulan uygulamasını bulabilmesi için aşağıdaki ProGuard kuralını eklemeniz gerekir:

-keep class * extends androidx.room3.RoomDatabase { <init>(); }

Kotlin Multiplatform'a geçiş

Room, başlangıçta Android kitaplığı olarak geliştirildi ve daha sonra API uyumluluğuna odaklanılarak KMP'ye taşındı. Room'un KMP sürümü, platformlar arasında ve Android'e özel sürümden biraz farklıdır. Bu farklılıklar aşağıda listelenmiş ve açıklanmıştır.

Support SQLite'tan SQLite Driver'a geçiş

androidx.sqlite.db içindeki SupportSQLiteDatabase ve diğer API'lerin tüm kullanımlarının SQLite Sürücü API'leri ile yeniden düzenlenmesi gerekir. Bunun nedeni, androidx.sqlite.db içindeki API'lerin yalnızca Android'e özel olmasıdır (KMP paketinden farklı pakete dikkat edin).

Geriye dönük uyumluluk için ve RoomDatabase, SupportSQLiteOpenHelper.Factory ile yapılandırıldığı sürece (ör. SQLiteDriver ayarlanmamışsa) Room, hem Support SQLite hem de SQLite Sürücü API'lerinin beklendiği gibi çalıştığı "uyumluluk modunda" çalışır. Bu sayede, tüm Support SQLite kullanımlarınızı tek bir değişiklikle SQLite Driver'a dönüştürmeniz gerekmez.

Room SQLite sarmalayıcısını kullanma

androidx.room3:room3-sqlite-wrapper yapısı, taşıma sırasında SQLiteDriver ile SupportSQLiteDatabase arasında köprü oluşturmak için API'ler sağlar.

SQLiteDriver ile yapılandırılmış bir RoomDatabase üzerinden SupportSQLiteDatabase almak için yeni uzantı işlevi RoomDatabase.getSupportWrapper kullanın. Bu uyumluluk sarmalayıcısı, özellikle BundledSQLiteDriver kullanmak isteyen kapsamlı SupportSQLite API kullanımlarına sahip kod tabanları için SQLiteDriver'yi benimserken genellikle RoomDatabase.openHelper.writableDatabase'den elde ettiğiniz mevcut SupportSQLiteDatabase kullanımlarını korumaya yardımcı olur.

Taşıma alt sınıflarını dönüştürme

Taşıma alt sınıflarının, SQLite sürücüsü karşılıklarına taşınması gerekir:

Kotlin Multiplatform

Taşıma alt sınıfları

object Migration_1_2 : Migration(1, 2) {
    override suspend fun migrate(connection: SQLiteConnection) {
        // ...
    }
}

Otomatik taşıma spesifikasyonu alt sınıfları

class AutoMigrationSpec_1_2 : AutoMigrationSpec {
    override suspend fun onPostMigrate(connection: SQLiteConnection) {
        // ...
    }
}

Yalnızca Android

Taşıma alt sınıfları

object Migration_1_2 : Migration(1, 2) {
  override fun migrate(db: SupportSQLiteDatabase) {
    // …
  }
}

Otomatik taşıma spesifikasyonu alt sınıfları

class AutoMigrationSpec_1_2 : AutoMigrationSpec {
  override fun onPostMigrate(db: SupportSQLiteDatabase) {
    // …
  }
}

Veritabanı geri çağırmasını dönüştürme

Veritabanı geri çağırmalarının SQLite sürücüsündeki karşılıklarına taşınması gerekir:

Kotlin Multiplatform

object MyRoomCallback : RoomDatabase.Callback() {
    override suspend fun onCreate(connection: SQLiteConnection) {
        // ...
    }

    override suspend fun onDestructiveMigration(connection: SQLiteConnection) {
        // ...
    }

    override suspend fun onOpen(connection: SQLiteConnection) {
        // ...
    }
}

Yalnızca Android

object MyRoomCallback : RoomDatabase.Callback() {
  override fun onCreate(db: SupportSQLiteDatabase) {
    // …
  }

  override fun onDestructiveMigration(db: SupportSQLiteDatabase) {
    // …
  }

  override fun onOpen(db: SupportSQLiteDatabase) {
    // …
  }
}

@RawQuery DAO işlevini dönüştürme

Android platformu dışı platformlar için derlenen ve @RawQuery ile ek açıklama eklenen işlevlerin, SupportSQLiteQuery yerine RoomRawQuery türünde bir parametre beyan etmesi gerekir.

Kotlin Multiplatform

Ham sorguyu tanımlama

@Dao
interface TodoDao {
    @RawQuery
    suspend fun getTodos(query: RoomRawQuery): List<TodoEntity>
}

Ardından, çalışma zamanında sorgu oluşturmak için RoomRawQuery kullanılabilir:

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

Yalnızca Android

Ham sorguyu tanımlama

@Dao
interface TodoDao {
  @RawQuery
  suspend fun getTodos(query: SupportSQLiteQuery): List<TodoEntity>
}

Ardından, çalışma zamanında sorgu oluşturmak için SimpleSQLiteQuery kullanılabilir:

suspend fun AndroidOnlyDao.getTodosWithLowercaseTitle(title: String): List<TodoEntity> {
  val query = SimpleSQLiteQuery(
      query = "SELECT * FROM TodoEntity WHERE title = ?",
      bindArgs = arrayOf(title.lowercase())
  )
  return getTodos(query)
}

Engelleme yapan DAO işlevlerini dönüştürme

Room, Kotlin'in birden fazla platform için sunduğu, özellik açısından zengin eşzamansız kotlinx.coroutines kitaplığından yararlanır. En iyi işlevsellik için suspend işlevleri, KMP projesinde derlenen DAO'lar için zorunlu kılınır. Mevcut kod tabanıyla geriye dönük uyumluluğu korumak için androidMain içinde uygulanan DAO'lar bu kapsamda değildir. KMP için Room kullanılırken Android platformu dışı platformlar için derlenen tüm DAO işlevlerinin suspend işlevleri olması gerekir.

Kotlin Multiplatform

Sorguları askıya alma

@Query("SELECT * FROM Todo")
suspend fun getAllTodos(): List<Todo>

İşlemleri askıya alma

@Transaction
suspend fun transaction() {
    // ...
}

Yalnızca Android

Sorguları engelleme

@Query("SELECT * FROM Todo")
fun getAllTodos(): List<Todo>

İşlemleri engelleme

@Transaction
fun blockingTransaction() { … }

Reaktif türleri Flow'a dönüştürme

Tüm DAO işlevlerinin askıya alma işlevi olması gerekmez. LiveData veya RxJava'nın Flowable gibi reaktif türler döndüren DAO işlevleri, askıya alma işlevlerine dönüştürülmemelidir. Ancak LiveData gibi bazı türler KMP ile uyumlu değildir. Reaktif dönüş türlerine sahip DAO işlevleri, eş yordam akışlarına taşınmalıdır.

Kotlin Multiplatform

Tepkisel türler Flows

@Query("SELECT * FROM Todo")
fun getTodosFlow(): Flow<List<Todo>>

Yalnızca Android

LiveData veya RxJava'nın Flowable gibi reaktif türleri

@Query("SELECT * FROM Todo")
fun getTodosLiveData(): LiveData<List<Todo>>

İşlem API'lerini dönüştürme

Room KMP için veritabanı işlemi API'leri, yazma (useWriterConnection) ve okuma (useReaderConnection) işlemleri arasında ayrım yapabilir.

Kotlin Multiplatform

val database: RoomDatabase = getRoomDatabase(builder)
database.useWriterConnection { transactor ->
    transactor.immediateTransaction {
        // perform database operations in transaction.
    }
}

Yalnızca Android

val database: RoomDatabase = …
database.withTransaction {
  // perform database operations in transaction
}

Yazma işlemleri

Okuyucuların verilere tutarlı bir şekilde erişebilmesi için birden fazla sorgunun verileri atomik olarak yazmasını sağlamak üzere yazma işlemlerini kullanın. Bunu, üç işlem türünden herhangi biriyle useWriterConnection kullanarak yapabilirsiniz:

  • immediateTransaction: Write-Ahead Logging (WAL) modunda (varsayılan), bu tür işlemler başladığında kilitlenir ancak okuyucular okumaya devam edebilir. Çoğu durumda tercih edilen seçenek budur.

  • deferredTransaction: İşlem, ilk yazma ifadesine kadar kilitlenmez. İşlem içinde yazma işleminin gerekli olup olmadığından emin değilseniz optimizasyon olarak bu işlem türünü kullanın. Örneğin, yalnızca oynatma listesinin adını vererek bir oynatma listesinden şarkı silmek için işlem başlatırsanız ve oynatma listesi mevcut değilse yazma (silme) işlemi gerekmez.

  • exclusiveTransaction: Bu mod, WAL modundaki immediateTransaction ile aynı şekilde davranır. Diğer günlük kaydı modlarında, işlem devam ederken diğer veritabanı bağlantılarının veritabanını okumasını engeller.

İşlemleri okuma

Veritabanından birden fazla kez tutarlı bir şekilde okuma yapmak için okuma işlemlerini kullanın. Örneğin, iki veya daha fazla ayrı sorgunuz olduğunda ve JOIN yan tümcesi kullanmadığınızda. Okuyucu bağlantılarında yalnızca ertelenen işlemlere izin verilir. Okuyucu bağlantısında anında veya özel bir işlem başlatmaya çalışmak, "yazma" işlemi olarak kabul edildiğinden istisnaya neden olur.

val database: RoomDatabase = getRoomDatabase(builder)
database.useReaderConnection { transactor ->
    transactor.deferredTransaction {
        // perform database operations in transaction.
    }
}

Kotlin Multiplatform'da kullanılamaz

Android'de kullanılabilen API'lerden bazıları Kotlin Multiplatform'da kullanılamaz.

Sorgu geri çağırma

Sorgu geri çağırmalarını yapılandırmak için kullanılan aşağıdaki API'ler ortak olarak kullanılamaz. Bu nedenle, Android dışındaki platformlarda kullanılamaz.

  • RoomDatabase.Builder.setQueryCallback
  • RoomDatabase.QueryCallback

Otomatik kapanan veritabanı

Zaman aşımından sonra otomatik kapanmayı etkinleştiren API (RoomDatabase.Builder.setAutoCloseTimeout) yalnızca Android'de kullanılabilir.

Önceden paketlenmiş veritabanı

Mevcut bir veritabanını (önceden paketlenmiş bir veritabanı) kullanarak RoomDatabase oluşturmaya yönelik aşağıdaki API'ler ortak olarak kullanılamaz ve bu nedenle Android dışındaki platformlarda kullanılamaz:

  • RoomDatabase.Builder.createFromAsset
  • RoomDatabase.Builder.createFromFile
  • RoomDatabase.Builder.createFromInputStream
  • RoomDatabase.PrepackagedDatabaseCallback

Aynı anda çalışan birden çok kopyanın geçersiz kılınması

Aynı anda çalışan birden çok kopyayı geçersiz kılmayı etkinleştiren API (RoomDatabase.Builder.enableMultiInstanceInvalidation) yalnızca Android'de kullanılabilir. Ortak veya diğer platformlarda kullanılamaz.