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ı, cihaz ağa erişemediğinde kullanıcının çevrimdışı olarak bu içeriğe göz atabilmesi için ilgili veri parçalarını önbelleğe almaktır.

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 notları.
  • Kolaylaştırılmış veritabanı taşıma yolları.

Bu nedenlerden dolayı, SQLite API'lerini doğrudan kullanmak yerine Room'u kullanmanızı önemle tavsiye ederiz.

Kurulum

Uygulamanızda Room'u kullanmak için uygulamanızın build.gradle dosyasına aşağıdaki bağımlılıkları ekleyin.

Kotlin

dependencies {
    val room_version = "2.7.2"

    implementation("androidx.room:room-runtime:$room_version")

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See Add the KSP plugin to your project
    ksp("androidx.room:room-compiler:$room_version")

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor("androidx.room:room-compiler:$room_version")

    // optional - Kotlin Extensions and Coroutines support for Room
    implementation("androidx.room:room-ktx:$room_version")

    // optional - RxJava2 support for Room
    implementation("androidx.room:room-rxjava2:$room_version")

    // optional - RxJava3 support for Room
    implementation("androidx.room:room-rxjava3:$room_version")

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation("androidx.room:room-guava:$room_version")

    // optional - Test helpers
    testImplementation("androidx.room:room-testing:$room_version")

    // optional - Paging 3 Integration
    implementation("androidx.room:room-paging:$room_version")
}

Groovy

dependencies {
    def room_version = "2.7.2"

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

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See KSP Quickstart to add KSP to your build
    ksp "androidx.room:room-compiler:$room_version"

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor "androidx.room:room-compiler:$room_version"

    // optional - RxJava2 support for Room
    implementation "androidx.room:room-rxjava2:$room_version"

    // optional - RxJava3 support for Room
    implementation "androidx.room:room-rxjava3:$room_version"

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation "androidx.room:room-guava:$room_version"

    // optional - Test helpers
    testImplementation "androidx.room:room-testing:$room_version"

    // optional - Paging 3 Integration
    implementation "androidx.room:room-paging:$room_version"
}

Birincil bileşenler

Room'da üç ana bileşen bulunur:

  • Veritabanını tutan ve uygulamanızın kalıcı verilerine yönelik temel bağlantının 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 verilere sorgu göndermek, verileri güncellemek, eklemek ve silmek için kullanabileceği yöntemler 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 öğesi nesnelerinin örnekleri olarak alınır. Uygulama, tanımlanan veri varlıklarını 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.

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

Örnek uygulama

Bu bölümde, tek bir veri öğesi ve tek bir DAO içeren bir Room veritabanının örnek uygulaması sunulmaktadır.

Veri varlığı

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

Kotlin

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

Java

@Entity
public class User {
    @PrimaryKey
    public int uid;

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;
}

Room'daki veri varlıkları hakkında daha fazla bilgi edinmek için Room varlıklarını kullanarak verileri tanımlama konusuna bakın.

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ığı yöntemleri sağlar.

Kotlin

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

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

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

    @Insert
    fun insertAll(vararg users: User)

    @Delete
    fun delete(user: User)
}

Java

@Dao
public interface UserDao {
    @Query("SELECT * FROM user")
    List<User> getAll();

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    List<User> loadAllByIds(int[] userIds);

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

    @Insert
    void insertAll(User... users);

    @Delete
    void 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 uygulamanın kalıcı verilere erişim için kullandığı ana nokta 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 açıklanmalıdır.
  • Sınıf, RoomDatabase sınıfını 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ı, sıfır bağımsız değişkeni olan ve DAO sınıfının bir örneğini döndüren soyut bir yöntem tanımlamalıdır.

Kotlin

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

Java

@Database(entities = {User.class}, version = 1)
public abstract class AppDatabase extends RoomDatabase {
    public abstract UserDao userDao();
}

Not: Uygulamanız tek bir işlemde çalışıyorsa AppDatabase nesnesini oluştururken singleton 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:

Kotlin

val db = Room.databaseBuilder(
            applicationContext,
            AppDatabase::class.java, "database-name"
        ).build()

Java

AppDatabase db = Room.databaseBuilder(getApplicationContext(),
        AppDatabase.class, "database-name").build();

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

Kotlin

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

Java

UserDao userDao = db.userDao();
List<User> users = userDao.getAll();

Ek kaynaklar

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

Örnekler

Codelab uygulamaları

Bloglar