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

Kotlin Multiplatform ile deneme
Kotlin Multiplatform, veritabanı katmanının diğer platformlarla paylaşılmasına olanak tanır. KMP'de Room Database'i ayarlamayı ve kullanmayı öğ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ı, verilerin ilgili 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ı.
  • Tekrara kaçan ve hataya açık ortak metin kodunu en aza indiren kolaylık notları.
  • Kolaylaştırılmış veritabanı taşıma yolları.

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

Kurulum

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

Kotlin

dependencies {
    val room_version = "3.0.0"

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

Groovy

dependencies {
    def room_version = "3.0.0"

    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ı tutan ve uygulamanızın kalıcı verilerine yönelik temel bağlantı için ana erişim noktası olarak hizmet veren veritabanı sınıfı.
  • Uygulamanızın veritabanındaki tabloları temsil eden veri öğeleri.
  • Uygulamanızın veritabanındaki verileri sorgulamak, güncellemek, eklemek ve silmek için kullanabileceği işlevler sağlayan veri erişim nesneleri (DAO'lar).

Veritabanı sınıfı, uygulamanıza bu veritabanıyla ilişkili DAO örneklerini sağlar. Buna karşılık uygulama, 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 öğelerini ilgili tablolardaki satırları güncellemek veya eklemek için yeni satırlar oluşturmak üzere de kullanabilir. Ş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ı sunulmaktadır.

Veri varlığı

Aşağıdaki kod, User veri varlığını tanımlar. User öğesinin her ö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 verileri 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 kalıcı verilere erişmek için uygulamanın ana erişim noktası olarak kullanılı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 açıklanmalıdır.
  • Sınıf, RoomDatabase öğesini genişleten bir soyut sınıf olmalıdır.
  • Veritabanıyla ilişkili her DAO sınıfı için veritabanı sınıfı, herhangi bir bağımsız değişken almayan 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 işlemde çalışıyorsa AppDatabase nesnesi 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 erişmeniz nadiren gerekir.

Uygulamanız birden fazla işlemde çalışıyorsa veritabanı oluşturucu çağrınıza enableMultiInstanceInvalidation() ekleyin. Bu sayede, her işlemde AppDatabase örneğiniz olduğunda paylaşılan veritabanı dosyasını bir işlemde 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 veritabanının bir örneğini oluşturmak için aşağıdaki kodu kullanabilirsiniz:

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