Room 3.0

  
Room kalıcılık kitaplığı, SQLite'in tüm gücünden yararlanırken daha sağlam veritabanı erişimi sağlamak için SQLite üzerinde bir soyutlama katmanı sunar.
Son Güncelleme Kararlı Sürüm Sürüm Adayı Beta sürümü Alfa Sürümü
9 Eylül 2026 3.0.3 - - 3.1.0-alpha01

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ılarla ilgili bağımlılıkları ekleyin:

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

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.

Modern

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

Kotlin

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.

Modern

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

Kotlin

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 eklenmelidir.

Geri bildirim

Geri bildiriminiz Jetpack'in iyileştirilmesine yardımcı olur. Yeni sorunlar keşfederseniz veya bu kitaplığı iyileştirmeye yönelik fikirleriniz varsa 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 Sorun İzleyici belgelerini inceleyin.

Sürüm 3.1

Sürüm 3.1.0-alpha01

9 Eylül 2026

androidx.room3:room3-*:3.1.0-alpha01 iptal edilir. 3.1.0-alpha01 sürümü bu commit'leri içerir.

API Değişiklikleri

  • Bağlantı havuzu zaman aşımını yapılandırmaya olanak tanımak için setConnectionPoolTimeout(timeout: Duration), RoomDatabase.Builder'ye eklendi. (I24d07, b/404380974)
  • Şu Oda ek açıklamaları artık AnnotationTarget.PROPERTY içeriyor: @ColumnInfo, @PrimaryKey, @Relation, @Embedded, @Ignore ve @ColumnTypeConverters. Bu API değişiklikleri, Room'u "alan merkezli" yerine "özellik merkezli" yapar. Yani Room artık varlık sütunlarının veya sorgu veri sınıfı sonuç sütunlarının temsili olarak destek alanları olmayan özellikleri kullanabilir. Room'un bunları DAO işlevleri için kullanabilmesi amacıyla özelliklerin hâlâ kullanılabilir bir alıcısı ve kullanılabilir bir belirleyicisi olması ya da birincil oluşturucunun parçası olması gerekir. (I72058, b/438041176, b/521861812)

Hata Düzeltmeleri

  • Web'de ve sürücüleri askıya alma işleminde, bir işlem sırasında eş yordamın iptal edilmesinin veritabanının ve bağlantının kötü bir duruma girmesine neden olarak daha fazla kullanımını engellediği sorun düzeltildi. (If75c0, b/549860940)
  • Kotlin object uygulama AutoMigrationSpec desteği. (Id4077, b/215012591)
  • @Transaction sarmalayıcı DAO işlevleri kullanılırken Room'un IllegalMonitorStateException oluşturmasına neden olan gerileme düzeltildi. (I996d9, b/543285472, b/553140228)
  • Room içinde kotlin.uuid.Uuid için yerleşik sütun türü dönüştürücü desteği eklendi. (Icca77, b/525093264)
  • Room'un Kotlin kod oluşturucusu artık oluşturulan _Impl sınıflarında OPT_IN_USAGE_ERROR ve OPT_IN_USAGE öğelerini bastırıyor. Böylece DAO'lar ve varlıklar, freeCompilerArgs içinde -opt-in gerektirmeden @RequiresOptIn ile açıklama eklenmiş türleri (ör. kotlin.uuid.Uuid) kullanabiliyor. (I013bf, b/410607888)
  • Veritabanı kapatıldıktan sonra çağrıldığında, artık oda askıya alma sorguları ve geçersiz kılma izleyici işlemleri IllegalStateException istisnası oluşturacak. (I5755a, b/543076356)
  • AndroidSQLiteDriver yapılandırılmış olan ve bağlam geçişi yapan @Transaction DAO sarmalayıcı askıya alma işlevlerinde oluşabilecek kilitlenme düzeltildi. (886ac5, b/543285472)
  • İşleme sırasında gereksiz bir println() düzeltilir. Simon Marquis'e teşekkür ederiz. (b/532893031)
  • Başka bir veritabanının işleminde diğer veritabanı kullanımlarının karıştırılmasıyla ilgili, tanımlanmamış davranışa yol açan sorun düzeltildi. (b/437068912)

Sürüm 3.0

Sürüm 3.0.3

9 Eylül 2026

androidx.room3:room3-*:3.0.3 iptal edilir. 3.0.3 sürümü bu commit'leri içerir.

Hata Düzeltmeleri

  • @Transaction sarmalayıcı DAO işlevleri kullanılırken Room'un IllegalMonitorStateException oluşturmasına neden olan gerileme düzeltildi. (I996d9, b/543285472, b/553140228)
  • Web'de ve sürücüleri askıya alma işleminde, bir işlem sırasında eş yordamın iptal edilmesinin veritabanının ve bağlantının kötü bir duruma girmesine neden olarak daha fazla kullanımını engellediği sorun düzeltildi. (If75c0, b/549860940)

Sürüm 3.0.2

26 Ağustos 2026

androidx.room3:room3-*:3.0.2 iptal edilir. 3.0.2 sürümü bu commit'leri içerir.

Hata Düzeltmeleri

  • Veritabanı kapatıldıktan sonra çağrıldığında, artık oda askıya alma sorguları ve geçersiz kılma izleyici işlemleri IllegalStateException istisnası oluşturacak. (I5755a, b/543076356)
  • AndroidSQLiteDriver yapılandırılmış olan ve bağlam geçişi yapan @Transaction DAO sarmalayıcı askıya alma işlevlerinde oluşabilecek kilitlenme düzeltildi. (886ac5, b/543285472)

Sürüm 3.0.1

29 Temmuz 2026

androidx.room3:room3-*:3.0.1 iptal edilir. 3.0.1 sürümü bu commit'leri içerir.

Hata Düzeltmeleri

  • İşleme sırasında gereksiz bir println() düzeltilir. Simon Marquis'e teşekkür ederiz. (b/532893031)
  • Başka bir veritabanının işleminde diğer veritabanı kullanımlarının karıştırılmasıyla ilgili, tanımlanmamış davranışa yol açan sorun düzeltildi. (b/437068912)

Sürüm 3.0.0

1 Temmuz 2026

androidx.room3:room3-*:3.0.0 iptal edilir. 3.0.0 sürümü bu commit'leri içerir.

3.0.0 sürümündeki başlıca özellikler:

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

Temel 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 sınıf, Room'un ek açıklama işleyicisinin giriş noktasıdır.
  • Veritabanı bildirimi, veritabanı şemasını açıklayan bir veya daha fazla veri sınıfı içeriyor ve @Entity ile açıklama eklenmiş.
  • 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'lerini temel alıyor.
  • Yalnızca Kotlin kodu oluşturma.
  • Kotlin Symbol Processing (KSP) gereklidir.

Room 3.0, 2.x'e kıyasla yeni işlevler sunar.

  • JS ve WasmJS desteği
  • Özel DAO dönüş türleri
  • @Fts5 ek açıklaması aracılığıyla FTS5 desteği
  • Kotlin'de varsayılan parametre değeri desteği
  • Birincil anahtar oluşturma algoritmasını belirtmek için PrimaryKey.algorihtm özelliği
  • "WITHOUT ROWID" tabloları oluşturabilme
  • @Relation ile bileşik ilişki sütunu

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 yer alır. Bu nedenle, yeni bir Maven grubu ve yapay nesne kimlikleri de vardır. Ö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) gibi türlere referans vermez. RoomDatabase API'leri SupportSQLiteDatabase ile birlikte 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. Artık RoomDatabase oluşturmak için 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ş daha kolaydır. Çünkü bu geçiş, çoğunlukla içe aktarma referanslarının güncellenmesini içerir. 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 Room 3.0'da Java kodu oluşturma ve 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ı, varlıklar 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'in kullanılması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, ilgili API'leriyle birlikte kaldırılır. addObserver ve removeObserver. Veritabanı işlemine tepki verme mekanizması, createFlow() API aracılığıyla InvalidationTracker içinde oluşturulabilen eş yordam akışlarıdır.

Ö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. JavaScript ve WasmJs'yi de hedefleyen SQLiteDriver arayüzlerinin (androidx.sqlite:sqlite) ve yeni yapıda androidx.sqlite:sqlite-web bulunan yeni bir sürücünün WebWorkerSQLiteDriver yayınlanmasıyla birlikte, Room'u tüm büyük KMP platformlarını hedefleyen ortak kodda 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. Migration.onMigrate(), RoomDatabase.Callback.onCreate() ve PooledConnection.usePrepared() gibi işlevler bu türden işlevlere örnek verilebilir. Sürücü API'lerinde, eşzamansız API'ler tüm platformlarda, eşzamanlı API'ler ise web dışı hedeflerde yaygındır. 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 senkron adlarıyla (SQLiteConnection.executeSQL eklenerek) uzantıyı askıya alma işlevlerini de ekledi. API'ler, platformlara göre doğru varyantı çağıracak olan beklenen / gerçek bildirimler olduğundan proje hem web hem de web dışı platformları hedeflediğinde bu API'lerin kullanılması önerilir. 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ü başlatmak 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ı desteği 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 platformlardakiyle benzerdir:

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 İade 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 androidx.room3:room3-paging konumundaki dönüştürücü sınıfının artık 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ülerine taşındı:

Dönüş Türü Dönüştürücü sınıfı Yapı
PagingSource PagingSourceDaoReturnTypeConverter androidx.room3:room3-paging
Observable, Flowable, Completable, Single, Maybe RxDaoReturnTypeConverters androidx.room3:room3-rxjava3
ListenableFuture GuavaDaoReturnTypeConverter androidx.room3:room3-guava
LiveData LiveDataDaoReturnTypeConverter androidx.room3:room3-livedata

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

Bir @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 faydalı 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'sindeki KDoc'u inceleyin.

Sürüm 3.0.0-rc01

17 Haziran 2026

androidx.room3:room3-*:3.0.0-rc01 iptal edilir. 3.0.0-rc01 sürümü bu commit'leri içerir.

Yeni Özellikler

  • DAO sorgu sonuçlarında kullanılan veri sınıflarındaki varsayılan değerlere sahip parametreler için destek eklendi. Bir sütunu temsil eden ve varsayılan değeri olan bir oluşturucunun parçası olan bir özellik isteğe bağlı olarak kabul edilir ve sonuçtaki bir sütun için bu özellik gerekli değildir. (34279a, b/70762008, b/193531601)

API Değişiklikleri

  • Dönüşüm kapsamını daha iyi ayırt etmek ve @DaoReturnTypeConverter ile simetri sağlamak için @TypeConverter öğesini @ColumnTypeConverter olarak yeniden adlandırın. (I24420, b/438041176)
  • Sağlanan özel DAO dönüş türleri için bir API eklendi @ProvidedDaoReturnTypeConveter. (I2a8ad, b/517485682)
  • PrimaryKey.algorihtm özelliği, PrimaryKey.autoGenerate doğru olarak ayarlandığında birincil anahtar oluşturma algoritmasını belirtmek için eklendi. (I57944, b/70053837)

Sürüm 3.0.0-alpha06

3 Haziran 2026

androidx.room3:room3-*:3.0.0-alpha06 iptal edilir. 3.0.0-alpha06 sürümü bu commit'leri içerir.

API Değişiklikleri

  • @Entity adlı yeni bir açıklama özelliği ekleyin. Bu özellik withoutRowId olarak adlandırılır ve doğru olarak ayarlandığında WITHOUT ROWID seçeneği kullanılarak destekleyici SQLite tablosu oluşturulur. (Idb48e, b/472790803)

Sürüm 3.0.0-alpha05

19 Mayıs 2026

androidx.room3:room3-*:3.0.0-alpha05 iptal edilir. 3.0.0-alpha05 sürümü bu commit'leri içerir.

API Değişiklikleri

  • @Relation ve @Junction özelliklerini, parentColumns ve entityColumns özelliklerinin ilişkileri çözmek için anahtar olarak kullanılacak sütun adları dizisi olacak şekilde güncelleyerek bileşik ilişki anahtarlarını destekler. (I92196, b/64247765)

Sürüm 3.0.0-alpha04

6 Mayıs 2026

androidx.room3:room3-*:3.0.0-alpha04 iptal edilir. 3.0.0-alpha04 sürümü bu commit'leri içerir.

API Değişiklikleri

  • Oda'nın bağlantı havuzunu yapılandırmak için API'ler ekleyin. Oluşturucu işlevleri setSingleConnectionPool() ve setMultipleConnectionPool(), Room'un veritabanına açacağı maksimum bağlantı miktarını kontrol etmek için kullanılabilir. (I9700d, b/438041176, b/432820350)
  • Başka bir genel API yapılandırmaya referans vermediğinden Room's DatabaseConfiguration genel API'den kaldırıldı. (I5f1e9, b/438041176)

Hata Düzeltmeleri

  • OPFS'de (b/496255935) ortaya çıkan "veritabanı kilitlendi" sorunlarını önlemek için Web hedeflerinin tek bir bağlantı havuzu kullanmasını sağlayın.
  • Room'un çok büyük bir onValidateSchema oluşturması nedeniyle oluşan "Yöntem çok büyük" hatasını (tekrar) düzeltmeye çalışın. İşlev, ifadelerin miktarına göre bölünür ancak ölçüm kesin değildir. Bu hatayla karşılaşmaya devam ederseniz room.validationSplitSize ek açıklama işlemcisi seçeneğiyle Room'un bölme için sayacağı ifade miktarını ayarlayabilirsiniz. Varsayılan değer şu anda 300 ifade olarak ayarlanmıştır. Bu nedenle, sorun devam ediyorsa daha düşük bir sayı kullanın (b/493708172).

Sürüm 3.0.0-alpha03

8 Nisan 2026

androidx.room3:room3-*:3.0.0-alpha03 iptal edilir. 3.0.0-alpha03 sürümü bu commit'leri içerir.

API Değişiklikleri

  • @Database bildiriminde oluşturucuya referans verildiğinde hata analizi uyarısını önlemek için RoomDatabase'nın bağımsız değişken içermeyen oluşturucusunu herkese açık hale getirin. (I9bac2, b/494722261)
  • Android bağlamı almayan bir Room.inMemoryDatabaseBuilder ve Room.databaseBuilder sürümü ekleyin. Room 3.0'da bağlam ihtiyacı büyük ölçüde azaltılmıştır. Bu nedenle, Builder için isteğe bağlı bir değer olarak kullanılması, ortak kodda bellek içi veritabanlarının daha kolay oluşturulmasını sağlar. (I5d502, b/438041176)

Hata Düzeltmeleri

  • onValidateSchema işlevinin gövdesi çok büyük olduğunda (b/493708172) JVM ve Android tarafından oluşturulan kodda "kod çok büyük" hatası düzeltildi.

Sürüm 3.0.0-alpha02

25 Mart 2026

androidx.room3:room3-*:3.0.0-alpha02 iptal edilir. 3.0.0-alpha02 sürümü bu commit'leri içerir.

Yeni Özellikler

  • FTS5 desteği: @Fts5 ek açıklaması aracılığıyla Room'a FTS5 desteği eklendi. Buna FTS5 belirteçleyicileri için yeni sabitler (TOKENIZER_ASCII ve TOKENIZER_TRIGRAM) ve "detail" FTS seçeneği için bir enum (FULL, COLUMN ve NONE) dahildir. (I90934, b/146824830)
  • Oda Sayfalama Hedefleri: room3-paging'ya js, wasmJs, tvOS ve watchOS hedefleri eklendi. (Icffd3, b/432783733)

API Değişiklikleri

  • Çok platformlu clearAllTables(): clearAllTables() ortak hale getirilerek tüm platformlarda kullanılabilir. Ayrıca suspend işlevine dönüştürüldü. (I434ae, b/322846465)
  • Yıkıcı Taşıma: fallbackToDestructiveMigration API'lerinde dropAllTables için varsayılan bir parametre değeri eklendi. (Ica88b, b/438041176)

  • Deneysel API Değişiklikleri:

    1. Açıklama tabanlı API'lerin deneysel olarak işaretlenmesine izin vermek için @ExperimentalRoomApi, room-common olarak değiştirildi.

    2. Room veritabanı bildiriminde @ConstructedBy gereksinimini bastırmak için deneysel bir RoomWarning eklendi. Bu durumda DatabaseConstructor oluşturulmaz ve DatabaseBuilder üzerinden fabrika uygulaması sağlanmalıdır. (If5443)

Hata Düzeltmeleri

  • Sayfalama Kaynağı: Dönüştürme işlevinin OKUMA sorguları için tasarlandığını doğru şekilde belirtmek üzere PagingSourceDaoReturnTypeConverter güncellendi. (I3b067, b/139872302)

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) önemli bir sürüm güncellemesidir.

Temel 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 sınıf, Room'un ek açıklama işleyicisinin giriş noktasıdır.
  • Veritabanı bildirimi, veritabanı şemasını açıklayan bir veya daha fazla veri sınıfı içeriyor ve @Entity ile açıklama eklenmiş.
  • 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'lerini temel alıyor.
  • Yalnızca Kotlin kodu oluşturma.
  • Kotlin Symbol Processing (KSP) gereklidir.

Room 3.0, 2.x'e kıyasla yeni işlevler 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 yer alır. Bu nedenle, yeni bir Maven grubu ve yapay nesne kimlikleri de vardır. Ö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) gibi türlere referans vermez. RoomDatabase API'leri SupportSQLiteDatabase ile birlikte 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. Artık RoomDatabase oluşturmak için 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ı geçiş stratejisi geçerlidir. Room KMP Geçiş 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 Room 3.0'da Java kodu oluşturma ve 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ı, varlıklar 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'in kullanılması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, ilgili API'leriyle birlikte kaldırılır. addObserver ve removeObserver. Veritabanı işlemine tepki verme mekanizması, createFlow() API aracılığıyla InvalidationTracker içinde oluşturulabilen eş yordam akışlarıdır.

Ö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. JavaScript ve WasmJs'yi de hedefleyen SQLiteDriver arayüzlerinin (androidx.sqlite:sqlite) ve yeni yapıda androidx.sqlite:sqlite-web bulunan yeni bir sürücünün WebWorkerSQLiteDriver yayınlanmasıyla birlikte, Room'u tüm büyük KMP platformlarını hedefleyen ortak kodda 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. Migration.onMigrate(), RoomDatabase.Callback.onCreate() ve PooledConnection.usePrepared() gibi işlevler bu türden işlevlere örnek verilebilir. Sürücü API'lerinde, eşzamansız API'ler tüm platformlarda, eşzamanlı API'ler ise web dışı hedeflerde yaygındır. 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 senkron adlarıyla (SQLiteConnection.executeSQL eklenerek) uzantıyı askıya alma işlevlerini de ekledi. API'ler, platformlara göre doğru varyantı çağıracak olan beklenen / gerçek bildirimler olduğundan proje hem web hem de web dışı platformları hedeflediğinde bu API'lerin kullanılması önerilir. 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ü başlatmak 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ı desteği 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 platformlardakiyle benzerdir:

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 İade 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 androidx.room3:room3-paging konumundaki dönüştürücü sınıfının artık 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ülerine taşındı:

Dönüş Türü Dönüştürücü sınıfı Yapı
PagingSource PagingSourceDaoReturnTypeConverter androidx.room3:room3-paging
Observable, Flowable, Completable, Single, Maybe RxDaoReturnTypeConverters androidx.room3:room3-rxjava3
ListenableFuture GuavaDaoReturnTypeConverter androidx.room3:room3-guava
LiveData LiveDataDaoReturnTypeConverter androidx.room3:room3-livedata

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

Bir @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 faydalı 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'sindeki KDoc'u inceleyin.