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

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ütunun bu özellik için gerekli olması gerekmez. (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 true olarak ayarlandığında birincil anahtar oluşturma algoritmasını belirtmek için PrimaryKey.algorihtm özelliği eklendi.PrimaryKey.autoGenerate (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

• Room'un 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ıldı. 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. Bu değişiklikler arasında 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) yer alıyor. (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 şartını 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 (androidx.room3 paketi), 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, geriye dönük uyumsuzluk yaratan 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 artık androidx.room3:room3-runtime oldu ve androidx.room.RoomDatabase gibi sınıflar artık androidx.room3.RoomDatabase konumunda 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. 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ı strateji 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ğun olduğu 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 doğrusu, 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'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, 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, bahsedilen API'lerin senkron adlarıyla askıya alma uzantısı işlevlerini de ekledi (SQLiteConnection.executeSQL eklenerek). Bu API'ler, projede hem web hem de web dışı platformlar hedeflendiğinde önerilir. Bunun nedeni, API'lerin platformlara göre doğru varyantı çağıracak olan beklenen / gerçek bildirimler 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ü 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üleri 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 sonucunun, ek açıklamalı işlev tarafından tanımlanan özel bir türe dönüştürülmesini 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ü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 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 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'sindeki KDoc'u inceleyin.