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 mengetahui informasi tentang cara menggunakan plugin KSP, lihat dokumentasi mulai cepat KSP.

Untuk informasi selengkapnya tentang dependensi, lihat Menambahkan Dependensi Build.

Menggunakan Plugin Gradle Room

Anda dapat menggunakan Plugin Gradle Room untuk mengonfigurasi opsi bagi compiler Room. Plugin mengonfigurasi project sehingga skema yang dihasilkan (yang merupakan output 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 Gradle Room. Tindakan ini akan mengonfigurasi compiler Room dan berbagai tugas kompilasi serta backend-nya (kotlinc, KSP) untuk menghasilkan file skema ke dalam folder beraroma, misalnya schemas/flavorOneDebug/com.package.MyDatabase/1.json. File ini harus diperiksa ke 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-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 Kotlin Multiplatform (KMP).

API anotasi inti tetap sama dengan komponen utamanya:

• 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.
• Pada 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 yang menyebabkan gangguan antara Room 2.x adalah sebagai berikut:

• Paket baru, androidx.room3.
• API SupportSQLite 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 menyebabkan gangguan, 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 di paket baru, yang berarti Room 3.0 juga memiliki ID grup dan ID artefak Maven 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 API SupportSQLite

Room 3.0 didukung sepenuhnya oleh API SQLiteDriver dan tidak lagi mereferensikan jenis SupportSQLite 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 bersama dengan 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 hanya melibatkan pembaruan referensi impor. Jika tidak, strategi migrasi yang sama dari Room di Android saja ke KMP akan berlaku. Lihat Panduan Migrasi Room KMP.

Wrapper SupportSQLite

Room 3.x mempertahankan wrapper SupportSQLite 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 First

Untuk mengembangkan library dengan lebih baik, Room 3.0 hanya menghasilkan kode Kotlin dan hanya merupakan Pemroses Simbol Kotlin (KSP). Dibandingkan dengan Room 2.x, tidak ada pembuatan kode Java dan konfigurasi pemroses anotasi melalui KAPT atau JavaAP tidak dapat dilakukan lagi di Room 3.0. Perhatikan bahwa KSP dapat memproses sumber Java dan compiler Room akan menghasilkan kode untuk database, entitas, 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 kode lainnya.

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

Tidak seperti Room 2.x, RoomDatabase tidak dapat lagi dikonfigurasi dengan Executor, tetapi CoroutineContext beserta dispatcher dapat disediakan melalui builder database.

API InvalidationTracker di Room 3.0 berbasis Flow, InvalidationTracker.Observer dihapus bersama dengan API addObserver dan removeObserver yang relevan. Mekanisme untuk bereaksi terhadap operasi database adalah melalui Coroutine Flow 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. Jika digabungkan dengan rilis antarmuka SQLiteDriver (androidx.sqlite:sqlite) yang juga menargetkan JavaScript dan WasmJs serta driver WebWorkerSQLiteDriver baru yang ada 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, API Room yang menggunakan SQLiteStatement sebagai argumen kini menjadi fungsi yang ditangguhkan. Contoh fungsi ini adalah Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared(), dan lainnya. Di API driver, API asinkron umum di semua platform dan API 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 mempermudah, paket androidx.sqlite juga menambahkan fungsi ekstensi suspend dengan nama sinkron dari API yang disebutkan (dengan penambahan SQLiteConnection.executeSQL). API ini direkomendasikan saat project menargetkan platform web dan non-web karena API adalah deklarasi expect / actual yang akan memanggil varian yang tepat berdasarkan platform. API ini adalah API yang digunakan runtime Room 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 penerapan 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. Instance ini menggunakan WASM SQLite dan menyimpan database di OPFS. Pekerja contoh dipublikasikan sebagai paket NPM lokal dan berkat dukungan Kotlin untuk dependensi NPM, modul KMP kecil dapat dibuat untuk melayani pekerja.

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

Setelah pekerja disiapkan di project, mengonfigurasi Room untuk Web sama 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 driver Web mungkin berisi worker default yang dipublikasikan di NPM, sehingga menyederhanakan penyiapan web.

Jenis Nilai yang Ditampilkan DAO Kustom

Berbagai integrasi jenis pengembalian DAO seperti untuk RxJava dan Paging telah diubah untuk menggunakan API baru di Room 3.0 yang disebut pengonversi jenis pengembalian DAO. Fungsi konverter jenis nilai yang ditampilkan DAO (@DaoReturnTypeConverter) memungkinkan mengubah 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 anotasi @DaoReturnTypeConverters dalam deklarasi @Database atau @Dao.

Misalnya, agar kueri DAO menampilkan PagingSource, class konverter yang ada 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() }
    }
}

Konverter 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) Menyediakan akses ke instance RoomDatabase, yang dapat berguna untuk melakukan operasi database tambahan atau mengakses cakupan coroutine.
• tableNames: Array<String>: (Opsional) Berisi tabel yang diakses dari kueri, berguna untuk mendukung jenis yang dapat diamati / reaktif saat digabungkan dengan API InvalidationTracker.createFlow() Room.
• rawQuery: RoomRawQuery: (Opsional) Berisi instance kueri saat runtime, sehingga 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 konverter jenis nilai yang ditampilkan DAO, lihat KDoc di @DaoReturnTypeConverter API.