Room 3.0

Bağımlılıkları bildirme

Room3'e bağımlılık eklemek için Google Maven deposunu projenize eklemeniz gerekir. Daha fazla bilgi için Google'ın Maven deposunu okuyun.

Uygulamanız veya modülünüz için build.gradle dosyasına ihtiyacınız olan yapıtların bağımlılıklarını ekleyin:

dependencies {
    val room_version = ""

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

dependencies {
    def room_version = ""

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

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

KSP eklentisini kullanmayla ilgili bilgi için KSP hızlı başlangıç dokümanlarına bakın.

Bağımlılıklar hakkında daha fazla bilgi için Derleme Bağımlılıkları Ekleme başlıklı makaleyi inceleyin.

Room Gradle eklentisini kullanma

Room derleyicisi için seçenekleri yapılandırmak üzere Room Gradle eklentisini kullanabilirsiniz. Eklenti, projeyi oluşturulan şemaların (derleme görevlerinin çıktısıdır ve otomatik taşımalar için kullanılır) tekrarlanabilir ve önbelleğe alınabilir derlemelere sahip olacak şekilde doğru yapılandırılmasını sağlayacak şekilde yapılandırır.

Eklentiyi eklemek için üst düzey Gradle derleme dosyanızda eklentiyi ve sürümünü tanımlayın.

plugins {
    id 'androidx.room3' version "$room_version" apply false
}

plugins {
    id("androidx.room3") version "$room_version" apply false
}

Modül düzeyindeki Gradle derleme dosyasında eklentiyi uygulayın ve room3 uzantısını kullanın.

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

plugins {
    id("androidx.room3")
}

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

Room Gradle eklentisi kullanılırken schemaDirectory ayarlanması gerekir. Bu işlem, Room derleyicisini ve çeşitli derleme görevlerini ve arka uçlarını (kotlinc, KSP) şema dosyalarını aromalı klasörlere (ör. schemas/flavorOneDebug/com.package.MyDatabase/1.json) çıkacak şekilde yapılandırır. Bu dosyalar, doğrulama ve otomatik taşıma işlemleri için kullanılmak üzere depoya kaydedilmelidir.

Geri bildirim

Geri bildiriminiz Jetpack'in iyileştirilmesine yardımcı olur. Yeni sorunlar keşfederseniz veya bu kitaplığı iyileştirmeye yönelik fikirleriniz olursa lütfen bize bildirin. Yeni bir sorun oluşturmadan önce lütfen bu kitaplıktaki mevcut sorunlara göz atın. Yıldız düğmesini tıklayarak mevcut bir soruna oyunuzu ekleyebilirsiniz.

Yeni sorun oluşturma

Daha fazla bilgi için Issue Tracker belgelerini inceleyin.

Sürüm 3.0

Sürüm 3.0.0-alpha01

11 Mart 2026

androidx.room3:room3-*:3.0.0-alpha01 iptal edilir.

Room 3.0 (paket androidx.room3), Kotlin Multiplatform'a (KMP) odaklanan Room 2.x paketinin (androidx.room) büyük bir sürüm güncellemesidir.

Temel ek açıklama API'leri ve ana bileşenler aynı kalır:

• androidx.room3.RoomDatabase sınıfını genişleten ve @Database ile ek açıklama eklenen soyut bir sınıf, Room'un ek açıklama işleyicisinin giriş noktasıdır.
• Veritabanı bildirimi, veritabanı şemasını açıklayan ve @Entity ile ek açıklama eklenmiş bir veya daha fazla veri sınıfı içeriyor.
• Veritabanı işlemleri, SQL ifadeleri @Query ek açıklamasıyla tanımlanan sorgu işlevlerini içeren @Dao bildirimlerinde tanımlanır.
• Çalışma zamanında, veritabanı uygulaması, veritabanını yapılandırmak için de kullanılan bir RoomDatabase.Builder aracılığıyla elde edilebilir.

Room kullanarak verileri yerel veritabanına kaydetme kılavuzundaki belgelerin çoğu Room 3.0 için de geçerlidir.

Room 2.x ile önceki sürümler arasındaki temel uyumsuzluklar şunlardır:

• Yeni paket, androidx.room3.
• androidx.room3:room3-sqlite-wrapper kullanmıyorsanız SupportSQLite API'leri artık desteklenmiyor.
• Tüm veritabanı işlemleri artık Coroutine API'lerine dayanmaktadır.
• Yalnızca Kotlin kodu üretimi.
• Kotlin Symbol Processing (KSP) gereklidir.

Room 3.0, uyumluluğu bozan değişikliklerin yanı sıra 2.x'e kıyasla yeni işlevler de sunar:

• JS ve WasmJS desteği
• Özel DAO dönüş türleri

Yeni Paket

Mevcut Room 2.x uygulamalarıyla uyumluluk sorunlarını önlemek ve Room'a geçişli bağımlılıkları olan kitaplıklar (ör. WorkManager) için Room 3.0 yeni bir pakette bulunur. Bu da yeni bir Maven grubu ve yapay nesne kimliklerine sahip olduğu anlamına gelir. Örneğin, androidx.room:room-runtime, androidx.room3:room3-runtime olarak değiştirildi ve androidx.room.RoomDatabase gibi sınıflar artık androidx.room3.RoomDatabase adresinde yer alacak.

SupportSQLite API'leri yok

Room 3.0, SQLiteDriver API'leri tarafından tamamen desteklenir ve artık SupportSQLite türleri (ör. SupportSQLiteDatabase) veya Android türleri (ör. Cursor) referansını içermez. RoomDatabase API'leri SupportSQLiteDatabase ile aynı işlevi gördüğünden ve SupportSQLiteOpenHelper almak için kullanılan API kaldırıldığından bu değişiklik, Room 3.0 ile 2.x arasındaki en önemli değişikliktir. RoomDatabase oluşturmak için artık SQLiteDriver gereklidir.

Örneğin, doğrudan veritabanı işlemleri için kullanılan API'ler, sürücü eşdeğerleriyle değiştirilir:

// Room 2.x
roomDatabase.runInTransaction { ... }

// Room 3.x
roomDatabase.withWriteTransaction { ... }

// Room 2.x
roomDatabase.query("SELECT * FROM Song").use { cursor -> ... }

// Room 3.x
roomDatabase.useReaderConnection { connection ->
  connection.usePrepared("SELECT * FROM Song") { stmt -> ... }
}

SupportSQLiteDatabase bağımsız değişkenine sahip geri çağırma API'leri de SQLiteConnection bağımsız değişkenine sahip eşdeğer API'leriyle değiştirildi. Bunlar, Migration.onMigrate() ve AutoMigrationSpec.onPostMigrate() gibi taşıma geri çağırma işlevlerinin yanı sıra RoomDatabase.Callback.onCreate(), RoomDatabase.Callback.onOpen() gibi veritabanı geri çağırma işlevleridir.

Room, KMP projesinde kullanılıyorsa 3.0'a geçiş, çoğunlukla içe aktarma referanslarının güncellenmesini içerdiğinden daha kolaydır. Aksi takdirde, yalnızca Android'de Room'dan KMP'ye geçiş için aynı taşıma stratejisi geçerlidir. Room KMP Taşıma Kılavuzu'na bakın.

SupportSQLite Wrapper

Room 3.x, geçişleri kolaylaştırmak için 2.x'te oluşturulan SupportSQLite sarmalayıcısını korur ve artık yeni bir yapıda androidx.room3:room3-sqlite-wrapper bulunur. Uyumluluk API'si, RoomDatabase öğesini SupportSQLiteDatabase öğesine dönüştürmenize olanak tanır. roomDatabase.openHelper.writableDatabase çağrıları roomDatabase.getSupportWrapper() ile değiştirilebilir.

Kotlin ve Eş Yordamlar Öncelikli

Kitaplığın daha iyi geliştirilmesi için Room 3.0 yalnızca Kotlin kodu oluşturur ve yalnızca bir Kotlin Sembol İşlemcisi'dir (KSP). Room 2.x'e kıyasla Java kodu oluşturma yoktur. Ayrıca, Room 3.0'da KAPT veya JavaAP aracılığıyla ek açıklama işlemcisinin yapılandırılması artık mümkün değildir. KSP'nin Java kaynaklarını işleyebildiğini ve Room derleyicisinin, kaynak bildirimleri Java'da olan veritabanı, öğe veya DAO'lar için kod oluşturacağını unutmayın. Room kullanımının yoğunlaştığı ve Kotlin Gradle eklentisi ile KSP'nin kod tabanının geri kalanını etkilemeden uygulanabileceği çok modüllü bir proje oluşturmanız önerilir.

Room 3.0, Coroutines kullanımını da gerektirir. Daha spesifik olarak, reaktif bir tür (ör. Flow veya özel bir DAO dönüş türü) döndürmedikleri sürece DAO işlevleri askıya alınmalıdır. Veritabanı işlemlerini gerçekleştirmek için kullanılan Room API'leri de askıya alma işlevleridir (ör. RoomDatabase.useReaderConnection ve RoomDatabase.useWriterConnection).

Room 2.x'in aksine, artık RoomDatabase ile Executor yapılandırmak mümkün değildir. Bunun yerine, veritabanının oluşturucusu aracılığıyla bir göndericiyle birlikte CoroutineContext sağlanabilir.

InvalidationTracker Room 3.0'daki API'ler Flow tabanlıdır, InvalidationTracker.Observer ve ilgili API'leri addObserver ve removeObserver kaldırılmıştır. Veritabanı işlemine tepki verme mekanizması, createFlow() API'si aracılığıyla oluşturulabilen eş yordam akışlarıdır.InvalidationTracker

Örnek kullanım:

fun getArtistTours(from: Date, to: Date): Flow<Map<Artist, TourState>> {
    return db.invalidationTracker.createFlow("Artist").map { _ ->
        val artists = artistsDao.getAllArtists()
        val tours = tourService.fetchStates(artists.map { it.id })
        associateTours(artists, tours, from, to)
    }
}

Web Desteği

Room 3.0 sürümü, KMP hedefleri olarak JavaScript ve WasmJs'yi ekler. Ayrıca JavaScript ve WasmJs'yi hedefleyen SQLiteDriver arayüzlerinin (androidx.sqlite:sqlite) ve yeni yapay nesne androidx.sqlite:sqlite-web içinde bulunan yeni bir sürücü WebWorkerSQLiteDriver'nin yayınlanmasıyla birlikte, tüm büyük KMP platformlarını hedefleyen ortak kodda Room'u kullanmak mümkündür.

Web platformlarının eşzamansız yapısı nedeniyle, bağımsız değişken olarak SQLiteStatement alan Room API'leri artık askıya alma işlevleridir. Bu işlevlere örnek olarak Migration.onMigrate(), RoomDatabase.Callback.onCreate() ve PooledConnection.usePrepared() verilebilir. Sürücü API'lerinde, tüm platformlarda ortak olarak kullanılan asenkron API'ler ve web dışı hedeflerde ortak olarak kullanılan senkron API'ler bulunur. Bu nedenle, web'i hedeflemeyen bir proje, ortak kodda senkron API'leri (SQLiteDriver.open(), SQLiteConnection.prepare() ve SQLiteStatement.step()) kullanmaya devam edebilir. Bu arada, yalnızca web'i hedefleyen bir proje, eşzamansız API'leri (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() ve SQLiteStatement.stepAsync()) kullanmalıdır.

Kolaylık sağlamak için androidx.sqlite paketi, belirtilen API'lerin eşzamanlı adlarıyla uzantı işlevlerini askıya alma işlevlerini de ekledi (SQLiteConnection.executeSQL eklenerek). Bu API'ler, proje hem web hem de web dışı platformları hedeflediğinde önerilir. Bunun nedeni, API'lerin platformlara göre doğru varyantı çağıracak olan beklenen / gerçek beyanlar olmasıdır. Bunlar, Room'un çalışma zamanında kullandığı ve desteklenen tüm platformlar için ortak kodda sürücü kullanımını etkinleştiren API'lerdir.

Örnek kullanım:

import androidx.sqlite.executeSQL
import androidx.sqlite.step

roomDatabase.useWriterConnection { connection ->
    val deletedSongs = connection.usePrepared(
        "SELECT count(*) FROM Song"
    ) { stmt ->
        stmt.step()
        stmt.getLong(0)
    }
    connection.executeSQL("DELETE FROM Song")
    deletedSongs
}

WebWorkerSQLiteDriver, ana iş parçacığı dışında veritabanı işlemi gerçekleştirmek için Web Worker ile iletişim kuran ve veritabanının Origin Private File System'de (OPFS) depolanmasını sağlayan bir SQLiteDriver uygulamasıdır. Sürücüyü örneklendirmek için basit bir iletişim protokolü uygulayan bir çalışan gerekir. Protokol, WebWorkerSQLiteDriver KDoc'ta açıklanmıştır.

Şu anda WebWorkerSQLiteDriver, iletişim protokolünü uygulayan varsayılan bir worker ile birlikte gönderilmemektedir. Ancak örnek olarak, androidx kod tabanında projenizde kullanılabilecek bir worker uygulaması bulunmaktadır. SQLite'ın WASM'sini kullanır ve veritabanını OPFS'de depolar. Örnek çalışan, yerel bir NPM paketi olarak yayınlanır ve Kotlin'in NPM bağımlılıklarını desteklemesi sayesinde, çalışana hizmet etmek için küçük bir KMP modülü oluşturulabilir.

Room için yerel bir web çalışanı kullanımını gösteren aşağıdaki GitHub projesine bakın.

Projeye bir çalışan eklendikten sonra Room for the Web'i yapılandırma işlemi diğer platformlardakine benzer:

fun createDatabase(): MusicDatabase {
    return Room.databaseBuilder<MusicDatabase>("music.db")
        .setDriver(WebWorkerSQLiteDriver(createWorker()))
        .build()
}

fun createWorker() =
    Worker(js("""new URL("sqlite-web-worker/worker.js", import.meta.url)"""))

Web sürücüsünün gelecekteki bir sürümünde, NPM'de yayınlanan varsayılan bir çalışan bulunabilir. Bu sayede web kurulumu daha kolay hale gelir.

Özel DAO dönüş türleri

RxJava ve Paging gibi çeşitli DAO dönüş türü entegrasyonları, Room 3.0'da DAO dönüş türü dönüştürücüler adı verilen yeni bir API kullanacak şekilde dönüştürüldü. DAO dönüş türü dönüştürücü işlevi (@DaoReturnTypeConverter), bir DAO işlevinin sonucunu, açıklama eklenmiş işlev tarafından tanımlanan özel bir türe dönüştürmeyi sağlar. Bu işlevler, sorgu sonuçlarını veri nesnelerine dönüştüren Room'un oluşturduğu koda katılmayı sağlar. DAO dönüş türü dönüştürücüleri içeren sınıflar, @Database veya @Dao bildirimlerindeki @DaoReturnTypeConverters ek açıklamaları aracılığıyla kaydedilmelidir.

Örneğin, bir DAO sorgusunun PagingSource döndürmesi için artık androidx.room3:room3-paging konumundaki dönüştürücü sınıfının kaydedilmesi gerekir:

@Dao
@DaoReturnTypeConverters(PagingSourceDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song)
    fun getSongsPaginated(): PagingSource<Int, Song>
}

Mevcut entegrasyonlar, DAO dönüş türü dönüştürücülere taşındı:

Sütun türü dönüştürücüler gibi, DAO dönüş türü dönüştürücüler de uygulama tarafından tanımlanabilir. Örneğin, bir uygulama, web türü için @DaoReturnTypeConverter tanımlayabilir kotlin.js.Promise.

object PromiseDaoReturnTypeConverter {
    @DaoReturnTypeConverter([OperationType.READ, OperationType.WRITE])
    fun <T> convert(
        db: RoomDatabase,
        executeAndConvert: suspend () -> T
    ): Promise<T> {
        return db.getCoroutineScope().promise { executeAndConvert() }
    }
}

Yukarıdaki dönüştürücü, DAO sorgu işlevlerinin Promise döndürmesine olanak tanır:

@Dao
@DaoReturnTypeConverters(PromiseDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song")
    fun getAllSongs(): Promise<List<Song>>
}

@DaoReturnTypeConverter işlevinin, sahip olması gereken parametre miktarı ve türleri açısından birkaç koşulu vardır. Olası parametreler şunlardır:

• db: RoomDatabase: (İsteğe bağlı) Ek veritabanı işlemleri gerçekleştirme veya eşzamanlılık kapsamına erişme konusunda yararlı olabilecek RoomDatabase örneğine erişim sağlar.
• tableNames: Array<String>: (İsteğe bağlı) Sorgunun erişilen tablolarını içerir. Room'un InvalidationTracker.createFlow() API'siyle birleştirildiğinde gözlemlenebilir / reaktif türleri desteklemek için kullanışlıdır.
• rawQuery: RoomRawQuery: (İsteğe bağlı) Çalışma zamanında sorgunun bir örneğini içerir. Bu sayede, PagingSourceDaoReturnTypeConverter tarafından uygulanan LIMIT / OFFSET stratejisi gibi dönüşümler etkinleştirilir.
• executeAndConvert: suspend () -> T: (Zorunlu) Sorguyu yürütecek ve sonucunu veri nesnelerine ayrıştıracak Room tarafından oluşturulan işlev.

DAO dönüş türü dönüştürücü oluşturma koşulları hakkında daha fazla bilgi için @DaoReturnTypeConverter API'siyle ilgili KDoc konusuna bakın.