Room'u kullanarak verileri yerel bir veritabanına kaydetme   Android Jetpack'in bir parçasıdır.

Kotlin Multiplatform ile deneyin
Kotlin Multiplatform, veritabanı katmanının diğer platformlarla paylaşılmasına olanak tanır. KMP'de Room veritabanını nasıl ayarlayacağınızı ve kullanacağınızı öğrenin.
KMP için Room veritabanını ayarlama →

Önemli miktarda yapılandırılmış veriyi işleyen uygulamalar, bu verileri yerel olarak kalıcı hale getirmekten büyük ölçüde yararlanabilir. En yaygın kullanım alanı, ilgili veri parçalarını önbelleğe almaktır. Böylece cihaz ağa erişemediğinde kullanıcılarınız çevrimdışı durumdayken bu içeriğe göz atmaya devam edebilir.

Room kalıcılık kitaplığı, SQLite'in tüm gücünden yararlanırken akıcı veritabanı erişimine olanak tanımak için SQLite üzerinde bir soyutlama katmanı sağlar. Özellikle Room aşağıdaki avantajları sunar:

  • SQL sorgularının derleme zamanında doğrulanması.
  • Tekrarlayan ve hataya açık ortak metin kodunu en aza indiren kolaylık ek açıklamaları.
  • Basitleştirilmiş veritabanı taşıma yolları.

SQLite API'lerini doğrudan kullanmak yerine Room'u kullanmanızı öneririz.

Kurulum

Uygulamanızda Room'u kullanmak için aşağıdaki bağımlılıkları modülünüzün build.gradle.kts dosyasına ekleyin. Room 3.0, ek açıklama işleme için KSP gerektirir.

Kotlin

dependencies {
    val room_version = "3.0.3"

    implementation("androidx.room3:room3-runtime:$room_version")
    ksp("androidx.room3:room3-compiler:$room_version")
}

Groovy

dependencies {
    def room_version = "3.0.3"

    implementation "androidx.room3:room3-runtime:$room_version"

    ksp "androidx.room3:room3-compiler:$room_version"
}

Birincil bileşenler

Oda'da üç ana bileşen bulunur:

  • Veritabanını barındıran ve uygulamanızın kalıcı verilerine yönelik temel bağlantı için ana erişim noktası olarak kullanılan veritabanı sınıfı.
  • Uygulamanızın veritabanındaki tabloları temsil eden veri varlıkları.
  • Uygulamanızın veritabanındaki verileri sorgulamak, güncellemek, eklemek ve silmek için kullanabileceği işlevleri sağlayan veri erişimi nesneleri (DAO'lar).

Veritabanı sınıfı, uygulamanıza bu veritabanıyla ilişkili DAO örneklerini sağlar. Uygulama da veritabanından veri almak için DAO'ları kullanabilir. Bu veriler, ilişkili veri varlığı nesnelerinin örnekleri olarak alınır. Uygulama, tanımlanan veri varlıklarını kullanarak ilgili tablolardaki satırları güncelleyebilir veya eklenecek yeni satırlar oluşturabilir. Şekil 1'de, Room'un farklı bileşenleri arasındaki ilişki gösterilmektedir.

Şekil 1. Room kitaplığı mimarisinin şeması.

Örnek uygulama

Bu bölümde, tek bir veri varlığı ve tek bir DAO içeren bir Room veritabanının örnek uygulaması gösterilmektedir.

Veri varlığı

Aşağıdaki kod, User veri varlığını tanımlar. Her User örneği, uygulamanın veritabanındaki bir user tablosunda bir satırı temsil eder.

@Entity
data class User(
    @PrimaryKey val uid: Int,
    @ColumnInfo(name = "first_name") val firstName: String,
    @ColumnInfo(name = "last_name") val lastName: String
)

Room'daki veri varlıkları hakkında daha fazla bilgi edinmek için Room varlıklarını kullanarak veri tanımlama başlıklı makaleyi inceleyin.

Veri erişimi nesnesi (DAO)

Aşağıdaki kod, UserDao adlı bir DAO'yu tanımlar. UserDao, uygulamanın geri kalanının user tablosundaki verilerle etkileşim kurmak için kullandığı işlevleri sağlar.

@Dao
interface UserDao {
    @Query("SELECT * FROM user")
    suspend fun getAll(): List<User>

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    suspend fun loadAllByIds(userIds: IntArray): List<User>

    @Query(
        """
        SELECT * FROM user
        WHERE first_name LIKE :first AND last_name LIKE :last LIMIT 1
        """
    )
    suspend fun findByName(first: String, last: String): User

    @Insert
    suspend fun insertAll(vararg users: User)

    @Delete
    suspend fun delete(user: User)
}

DAO'lar hakkında daha fazla bilgi edinmek için Room DAO'larını kullanarak verilere erişme başlıklı makaleyi inceleyin.

Veritabanı

Aşağıdaki kod, veritabanını tutacak bir AppDatabase sınıfı tanımlar. AppDatabase, veritabanı yapılandırmasını tanımlar ve uygulamaya ait kalıcı verilerin ana erişim noktası olarak işlev görür. Veritabanı sınıfı aşağıdaki koşulları karşılamalıdır:

  • Sınıf, veritabanıyla ilişkili tüm veri varlıklarını listeleyen bir entities dizisi içeren @Database ek açıklamasıyla ek açıklamalı olmalıdır.
  • Sınıf, RoomDatabase sınıfını genişleten soyut bir sınıf olmalıdır.
  • Veritabanı sınıfı, veritabanıyla ilişkili her DAO sınıfı için bağımsız değişken içermeyen ve DAO sınıfının bir örneğini döndüren soyut bir işlev tanımlamalıdır.

@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

Not: Uygulamanız tek bir süreçte çalışıyorsa AppDatabase nesnesini oluştururken tekil tasarım kalıbını kullanmanız gerekir. Her RoomDatabase örneği oldukça pahalıdır ve tek bir işlemde birden fazla örneğe nadiren erişmeniz gerekir.

Uygulamanız birden fazla işlemde çalışıyorsa veritabanı oluşturucu çağrınıza enableMultiInstanceInvalidation() ekleyin. Bu sayede, her işlemde bir AppDatabase örneğiniz olduğunda, bir işlemdeki paylaşılan veritabanı dosyasını geçersiz kılabilirsiniz. Bu geçersiz kılma işlemi, diğer işlemlerdeki AppDatabase örneklerine otomatik olarak yayılır.

Kullanım

Veri varlığını, DAO'yu ve veritabanı nesnesini tanımladıktan sonra aşağıdaki kodu kullanarak veritabanının bir örneğini oluşturabilirsiniz:

val db =
    Room.databaseBuilder<AppDatabase>(applicationContext, "database-name")
        .setDriver(AndroidSQLiteDriver())
        .build()

Ardından, AppDatabase içindeki soyut işlevleri kullanarak DAO'nun bir örneğini alabilirsiniz. Buna karşılık, veritabanıyla etkileşim kurmak için DAO örneğindeki işlevleri kullanabilirsiniz:

val userDao = db.userDao()
val users: List<User> = userDao.getAll()

Ek kaynaklar

Room hakkında daha fazla bilgi edinmek için aşağıdaki ek kaynaklara göz atın:

Örnekler