Room 3.0

Mendeklarasikan dependensi

Untuk menambahkan dependensi pada Room3, Anda harus menambahkan repositori Maven Google ke project Anda. Baca repositori Maven Google untuk mengetahui informasi selengkapnya.

Tambahkan dependensi untuk artefak yang diperlukan dalam file build.gradle bagi aplikasi atau modul Anda:

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

Untuk informasi tentang cara menggunakan plugin KSP, lihat dokumentasi memulai cepat KSP.

Untuk informasi selengkapnya tentang dependensi, lihat Menambahkan Dependensi Build.

Menggunakan Plugin Room Gradle

Anda dapat menggunakan Plugin Room Gradle untuk mengonfigurasi opsi untuk compiler Room. Plugin ini mengonfigurasi project sehingga skema yang dihasilkan (yang merupakan output dari tugas kompilasi dan digunakan untuk migrasi otomatis) dikonfigurasi dengan benar agar memiliki build yang dapat direproduksi dan di-cache.

Untuk menambahkan plugin, di file build Gradle level teratas, tentukan plugin dan versinya.

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

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

Dalam file build Gradle level modul, terapkan plugin dan gunakan ekstensi room3.

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

plugins {
    id("androidx.room3")
}

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

Menetapkan schemaDirectory diperlukan saat menggunakan Plugin Room Gradle. Tindakan ini akan mengonfigurasi compiler Room dan berbagai tugas kompilasi serta backend-nya (kotlinc, KSP) untuk menghasilkan file skema ke dalam folder yang diberi nama, misalnya schemas/flavorOneDebug/com.package.MyDatabase/1.json. File ini harus dimasukkan ke dalam repositori untuk digunakan dalam validasi dan migrasi otomatis.

Masukan

Masukan Anda membantu meningkatkan kualitas Jetpack. Beri tahu kami jika Anda menemukan masalah baru atau mempunyai masukan untuk meningkatkan kualitas library ini. Harap periksa masalah yang sudah diketahui dalam library ini sebelum membuat laporan baru. Anda dapat memberikan suara untuk masalah yang sudah diketahui dengan mengklik tombol bintang.

Laporkan masalah baru

Lihat dokumentasi Issue Tracker untuk informasi selengkapnya.

Versi 3.0

Versi 3.0.0-alpha04

06 Mei 2026

androidx.room3:room3-*:3.0.0-alpha04 dirilis. Versi 3.0.0-alpha04 berisi commit berikut.

Perubahan API

• Menambahkan API untuk mengonfigurasi kumpulan koneksi Room. Fungsi builder setSingleConnectionPool() dan setMultipleConnectionPool() dapat digunakan untuk mengontrol jumlah maksimum koneksi yang akan dibuka Room ke database. (I9700d, b/438041176, b/432820350)
• Menghapus DatabaseConfiguration Room dari API publik karena tidak ada API publik lain yang mereferensikan konfigurasi. (I5f1e9, b/438041176)

Versi 3.0.0-alpha03

08 April 2026

androidx.room3:room3-*:3.0.0-alpha03 dirilis. Versi 3.0.0-alpha03 berisi commit berikut.

Perubahan API

• Membuat konstruktor tanpa argumen RoomDatabase menjadi publik untuk menghindari peringatan Lint saat konstruktor direferensikan dalam deklarasi @Database. (I9bac2, b/494722261)
• Menambahkan versi Room.inMemoryDatabaseBuilder dan Room.databaseBuilder yang tidak menggunakan Konteks Android. Kebutuhan akan Konteks telah sangat berkurang di Room 3.0 sehingga menjadikannya nilai opsional untuk Builder memungkinkan pembuatan database dalam memori dalam kode umum dengan lebih mudah. (I5d502, b/438041176)

Perbaikan Bug

• Memperbaiki error 'kode terlalu besar' pada kode yang dihasilkan JVM dan Android saat isi fungsi onValidateSchema terlalu besar (b/493708172).

Versi 3.0.0-alpha02

25 Maret 2026

androidx.room3:room3-*:3.0.0-alpha02 dirilis. Versi 3.0.0-alpha02 berisi commit berikut.

Fitur Baru

• Dukungan FTS5: Menambahkan dukungan FTS5 ke Room melalui anotasi @Fts5. Hal ini mencakup konstanta baru untuk tokenizer FTS5 (TOKENIZER_ASCII dan TOKENIZER_TRIGRAM) dan enum untuk opsi FTS 'detail' (FULL, COLUMN, dan NONE). (I90934, b/146824830)
• Target Paging Room: Menambahkan target js, wasmJs, tvOS, dan watchOS ke room3-paging. (Icffd3, b/432783733)

Perubahan API

• Multiplatform clearAllTables(): Mengubah clearAllTables() menjadi umum, sehingga tersedia di semua platform. Fungsi ini juga telah dikonversi menjadi fungsi suspend. (I434ae, b/322846465)
• Migrasi Destruktif: Menambahkan nilai parameter default ke dropAllTables di fallbackToDestructiveMigration API. (Ica88b, b/438041176)

• Perubahan API Eksperimental:

  1. Memindahkan @ExperimentalRoomApi ke room-common agar API berbasis anotasi dapat ditandai sebagai eksperimental.

  2. Menambahkan RoomWarning eksperimental untuk menekan persyaratan @ConstructedBy dalam deklarasi database Room. Dalam hal ini, DatabaseConstructor tidak akan dibuat, dan implementasi factory harus disediakan melalui DatabaseBuilder. (If5443)

Perbaikan Bug

• Sumber Paging: Mengupdate PagingSourceDaoReturnTypeConverter untuk menunjukkan dengan benar bahwa fungsi konversinya ditujukan untuk kueri READ. (I3b067, b/139872302)

Versi 3.0.0-alpha01

11 Maret 2026

androidx.room3:room3-*:3.0.0-alpha01 dirilis.

Room 3.0 (paket androidx.room3) adalah update versi utama paket Room 2.x (androidx.room) yang berfokus pada Multiplatform Kotlin (KMP).

API anotasi inti tetap sama dengan komponen utama:

• Class abstrak yang memperluas androidx.room3.RoomDatabase dan diberi anotasi dengan @Database adalah titik entri untuk pemroses anotasi Room.
• Deklarasi database memiliki satu atau beberapa class data yang menjelaskan skema database dan diberi anotasi dengan @Entity.
• Operasi database ditentukan dalam deklarasi @Dao yang berisi fungsi kueri yang pernyataan SQL-nya ditentukan melalui anotasi @Query.
• Saat runtime, implementasi database dapat diperoleh melalui RoomDatabase.Builder yang juga digunakan untuk mengonfigurasi database.

Sebagian besar dokumentasi dalam panduan Menyimpan data di database lokal menggunakan Room masih relevan dengan Room 3.0.

Perbedaan utama antara Room 2.x adalah sebagai berikut:

• Paket baru, androidx.room3.
• SupportSQLite API tidak lagi didukung, kecuali jika Anda menggunakan androidx.room3:room3-sqlite-wrapper.
• Semua operasi database kini berbasis Coroutine API.
• Hanya pembuatan kode Kotlin.
• Pemrosesan Simbol Kotlin (KSP) diperlukan.

Selain perubahan yang dapat menyebabkan error, Room 3.0 menghadirkan fungsi baru dibandingkan dengan 2.x:

• Dukungan JS dan WasmJS
• Jenis Nilai yang Ditampilkan DAO Kustom

Paket Baru

Untuk mencegah masalah kompatibilitas dengan implementasi Room 2.x yang ada dan untuk library dengan dependensi transitif ke Room (misalnya, WorkManager), Room 3.0 berada dalam paket baru, yang berarti juga memiliki grup maven dan ID artefak baru. Misalnya, androidx.room:room-runtime telah menjadi androidx.room3:room3-runtime dan class seperti androidx.room.RoomDatabase kini akan berada di androidx.room3.RoomDatabase.

Tidak Ada SupportSQLite API

Room 3.0 sepenuhnya didukung oleh SQLiteDriver API dan tidak lagi mereferensikan SupportSQLite jenis seperti SupportSQLiteDatabase atau jenis Android seperti Cursor. Ini adalah perubahan paling signifikan antara Room 3.0 dan 2.x karena RoomDatabase API yang mencerminkan SupportSQLiteDatabase beserta API untuk mendapatkan SupportSQLiteOpenHelper telah dihapus. SQLiteDriver kini diperlukan untuk membuat RoomDatabase.

Misalnya, API untuk operasi database langsung diganti dengan driver yang setara:

// 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 -> ... }
}

Callback API yang memiliki SupportSQLiteDatabase sebagai argumen juga telah diganti dengan API yang setara yang memiliki SQLiteConnection sebagai argumen. Ini adalah fungsi callback migrasi seperti Migration.onMigrate() dan AutoMigrationSpec.onPostMigrate() beserta callback database seperti RoomDatabase.Callback.onCreate(), RoomDatabase.Callback.onOpen(), dll.

Jika Room digunakan dalam project KMP, migrasi ke 3.0 akan lebih sederhana karena sebagian besar melibatkan pembaruan referensi impor. Jika tidak, strategi migrasi yang sama dari Room di Android saja ke KMP akan berlaku. Lihat Panduan Migrasi KMP Room.

SupportSQLite Wrapper

Room 3.x mempertahankan SupportSQLite wrapper yang dibuat di 2.x untuk mempermudah migrasi dan kini berada di artefak baru androidx.room3:room3-sqlite-wrapper. API kompatibilitas memungkinkan Anda mengonversi RoomDatabase menjadi SupportSQLiteDatabase. Pemanggilan roomDatabase.openHelper.writableDatabase dapat diganti dengan roomDatabase.getSupportWrapper().

Kotlin dan Coroutine Pertama

Untuk mengembangkan library dengan lebih baik, Room 3.0 hanya menghasilkan kode Kotlin dan hanya Pemroses Simbol Kotlin (KSP). Dibandingkan dengan Room 2.x, tidak ada pembuatan kode Java dan konfigurasi pemroses anotasi melalui KAPT atau JavaAP tidak lagi memungkinkan di Room 3.0. Perhatikan bahwa KSP dapat memproses sumber Java dan compiler Room akan menghasilkan kode untuk database, entity, atau DAO yang deklarasi sumbernya ada di Java. Sebaiknya miliki project multi-modul tempat penggunaan Room terkonsentrasi dan Plugin Gradle Kotlin serta KSP dapat diterapkan tanpa memengaruhi bagian codebase lainnya.

Room 3.0 juga memerlukan penggunaan Coroutine, dan khususnya fungsi DAO harus ditangguhkan kecuali jika menampilkan jenis reaktif, seperti Flow atau jenis nilai yang ditampilkan DAO kustom. Room API untuk melakukan operasi database juga menangguhkan fungsi, seperti RoomDatabase.useReaderConnection dan RoomDatabase.useWriterConnection.

Berbeda dengan Room 2.x, Anda tidak dapat lagi mengonfigurasi RoomDatabase dengan Executor. Sebagai gantinya, CoroutineContext beserta dispatcher dapat disediakan melalui builder database.

InvalidationTracker API di Room 3.0 berbasis Flow, InvalidationTracker.Observer dihapus bersama dengan API relevannya addObserver dan removeObserver. Mekanisme untuk bereaksi terhadap operasi database adalah melalui Alur Coroutine yang dapat dibuat melalui createFlow() API di InvalidationTracker.

Contoh penggunaan:

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

Dukungan Web

Rilis Room 3.0 menambahkan JavaScript dan WasmJs sebagai target KMP. Dikombinasikan dengan rilis antarmuka SQLiteDriver (androidx.sqlite:sqlite) yang juga menargetkan JavaScript dan WasmJs serta driver baru WebWorkerSQLiteDriver yang berada di artefak baru androidx.sqlite:sqlite-web, Room dapat digunakan dalam kode umum yang menargetkan semua platform KMP utama.

Karena sifat platform web yang asinkron, Room API yang menggunakan SQLiteStatement sebagai argumen kini menangguhkan fungsi. Contoh fungsi ini adalah Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared(), dan lainnya. Di driver API, API asinkron umum di semua platform dan sinkron umum untuk target non-web. Oleh karena itu, project yang tidak menargetkan web dapat terus menggunakan API sinkron (SQLiteDriver.open(), SQLiteConnection.prepare(), dan SQLiteStatement.step()) dalam kode umum. Sementara itu, project yang hanya menargetkan web harus menggunakan API asinkron (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync(), dan SQLiteStatement.stepAsync()).

Untuk kemudahan, paket androidx.sqlite juga menambahkan fungsi ekstensi penangguhan dengan nama sinkron API yang disebutkan (dengan penambahan SQLiteConnection.executeSQL). API ini direkomendasikan saat project menargetkan platform web dan non-web karena API adalah deklarasi yang diharapkan / aktual yang akan memanggil varian yang tepat berdasarkan platform. Ini adalah penggunaan runtime Room API dan memungkinkan penggunaan driver dalam kode umum untuk semua platform yang didukung.

Contoh penggunaan:

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 adalah implementasi SQLiteDriver yang berkomunikasi dengan Web Worker untuk melakukan operasi database di luar thread utama dan memungkinkan penyimpanan database di Origin Private File System (OPFS). Untuk membuat instance driver diperlukan pekerja yang menerapkan protokol komunikasi sederhana, protokol ini dijelaskan dalam WebWorkerSQLiteDriver KDoc.

Saat ini, WebWorkerSQLiteDriver tidak dilengkapi dengan pekerja default yang menerapkan protokol komunikasi, tetapi sebagai contoh, codebase androidx berisi implementasi pekerja yang dapat digunakan dalam project Anda. Aplikasi ini menggunakan WASM SQLite dan menyimpan database di OPFS. Contoh pekerja dipublikasikan sebagai paket NPM lokal dan berkat dukungan Kotlin untuk dependensi NPM, modul KMP kecil dapat dibuat untuk menayangkan pekerja.

Lihat project GitHub berikut yang menunjukkan penggunaan pekerja web lokal untuk Room.

Setelah pekerja disiapkan dalam project, mengonfigurasi Room untuk Web mirip dengan platform lainnya:

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

Versi mendatang dari driver Web mungkin berisi pekerja default yang dipublikasikan di NPM, sehingga penyiapan web menjadi lebih sederhana.

Jenis Nilai yang Ditampilkan DAO Kustom

Berbagai integrasi jenis nilai yang ditampilkan DAO seperti untuk RxJava dan Paging telah diubah untuk menggunakan API baru di Room 3.0 yang disebut pengonversi jenis nilai yang ditampilkan DAO. Fungsi pengonversi jenis nilai yang ditampilkan DAO (@DaoReturnTypeConverter) memungkinkan transformasi hasil fungsi DAO menjadi jenis kustom yang ditentukan oleh fungsi yang diberi anotasi. Fungsi ini memungkinkan partisipasi dalam kode yang dihasilkan Room yang mengubah hasil kueri menjadi objek data. Class yang berisi pengonversi jenis nilai yang ditampilkan DAO harus didaftarkan melalui @DaoReturnTypeConverters anotasi dalam @Database atau @Dao deklarasi.

Misalnya, agar kueri DAO menampilkan PagingSource, class pengonversi yang berada di androidx.room3:room3-paging kini harus didaftarkan:

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

Integrasi yang ada telah dipindahkan ke pengonversi jenis nilai yang ditampilkan DAO:

Seperti pengonversi jenis kolom, pengonversi jenis nilai yang ditampilkan DAO dapat ditentukan oleh aplikasi. Misalnya, aplikasi dapat mendeklarasikan @DaoReturnTypeConverter untuk jenis web 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() }
    }
}

Pengonversi di atas kemudian memungkinkan fungsi kueri DAO menampilkan Promise:

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

Fungsi @DaoReturnTypeConverter memiliki beberapa persyaratan dalam jumlah parameter yang harus dimilikinya dan jenisnya. Parameter yang mungkin adalah:

• db: RoomDatabase: (Opsional) Memberikan akses ke instance RoomDatabase, yang dapat berguna untuk melakukan operasi database tambahan atau mengakses cakupan coroutine.
• tableNames: Array<String>: (Opsional) Berisi tabel kueri yang diakses, berguna untuk mendukung jenis reaktif / dapat diamati jika digabungkan dengan API InvalidationTracker.createFlow() Room.
• rawQuery: RoomRawQuery: (Opsional) Berisi instance kueri saat runtime, yang memungkinkan transformasi seperti strategi LIMIT / OFFSET yang diterapkan oleh PagingSourceDaoReturnTypeConverter.
• executeAndConvert: suspend () -> T: (Wajib) Fungsi yang dihasilkan Room yang akan menjalankan kueri dan mengurai hasilnya menjadi objek data.

Untuk mengetahui informasi selengkapnya tentang persyaratan untuk membuat pengonversi jenis nilai yang ditampilkan DAO, lihat KDoc di @DaoReturnTypeConverter API.