Room 3.0

ไลบรารีการคงอยู่ของ Room มีเลเยอร์การเปลี่ยนระดับนามธรรมเหนือ SQLite เพื่อให้เข้าถึงฐานข้อมูลได้อย่างมีประสิทธิภาพมากขึ้นในขณะที่ใช้ประโยชน์จากความสามารถทั้งหมดของ SQLite

อัปเดตล่าสุด	รุ่นที่เสถียร	รุ่นที่อาจได้รับการเผยแพร่	รุ่นเบต้า	รุ่นอัลฟ่า
11 มีนาคม 2026	-	-	-	3.0.0-alpha01

การประกาศทรัพยากร Dependency

หากต้องการเพิ่มทรัพยากร Dependency ใน Room3 คุณต้องเพิ่มที่เก็บ Maven ของ Google ลงในโปรเจ็กต์ อ่านข้อมูลเพิ่มเติมได้ที่ที่เก็บ Maven ของ Google

เพิ่มทรัพยากร Dependency สำหรับอาร์ติแฟกต์ที่ต้องการในไฟล์ build.gradle สำหรับ แอปหรือโมดูล

Kotlin

dependencies {
    val room_version = ""

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

Groovy

dependencies {
    def room_version = ""

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

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

ดูข้อมูลเกี่ยวกับการใช้ปลั๊กอิน KSP ได้ที่เอกสารประกอบฉบับย่อของ KSP

ดูข้อมูลเพิ่มเติมเกี่ยวกับการพึ่งพาได้ที่เพิ่มการพึ่งพาบิลด์

ใช้ปลั๊กอิน Gradle ของ Room

คุณสามารถใช้ปลั๊กอิน Gradle ของ Room เพื่อกำหนดค่าตัวเลือกสำหรับคอมไพเลอร์ Room ได้ ปลั๊กอินจะกำหนดค่าโปรเจ็กต์เพื่อให้สคีมาที่สร้างขึ้น (ซึ่งเป็นเอาต์พุตของงานคอมไพล์และใช้สำหรับการย้ายข้อมูลอัตโนมัติ) ได้รับการกำหนดค่าอย่างถูกต้องเพื่อให้มีการสร้างที่ทำซ้ำได้และแคชได้

หากต้องการเพิ่มปลั๊กอิน ให้กำหนดปลั๊กอินและเวอร์ชันในไฟล์ Gradle Build ระดับบนสุด

Groovy

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

Kotlin

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

ในไฟล์บิลด์ Gradle ระดับโมดูล ให้ใช้ปลั๊กอินและใช้ส่วนขยาย room3

Groovy

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

Kotlin

plugins {
    id("androidx.room3")
}

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

ต้องตั้งค่า schemaDirectory เมื่อใช้ปลั๊กอิน Gradle ของ Room ซึ่งจะกำหนดค่าคอมไพเลอร์ Room และงานการคอมไพล์ต่างๆ รวมถึงแบ็กเอนด์ (kotlinc, KSP) เพื่อส่งออกไฟล์สคีมาไปยังโฟลเดอร์ที่มีรสชาติ เช่น schemas/flavorOneDebug/com.package.MyDatabase/1.json คุณควร เช็คอินไฟล์เหล่านี้ในที่เก็บเพื่อใช้ในการตรวจสอบและการย้ายข้อมูลอัตโนมัติ

ความคิดเห็น

ความคิดเห็นของคุณช่วยเราปรับปรุง Jetpack ให้ดียิ่งขึ้น โปรดแจ้งให้เราทราบหากพบปัญหาใหม่หรือมี ไอเดียในการปรับปรุงไลบรารีนี้ โปรดดูปัญหาที่มีอยู่ ในไลบรารีนี้ก่อนสร้างปัญหาใหม่ คุณสามารถโหวตปัญหาที่มีอยู่ได้โดย คลิกปุ่มดาว

สร้างปัญหาใหม่

ดูข้อมูลเพิ่มเติมได้ในเอกสารประกอบของเครื่องมือติดตามปัญหา

เวอร์ชัน 3.0

เวอร์ชัน 3.0.0-alpha01

11 มีนาคม 2026

androidx.room3:room3-*:3.0.0-alpha01 ได้รับการเผยแพร่แล้ว

Room 3.0 (แพ็กเกจ androidx.room3) เป็นการอัปเดตเวอร์ชันหลักของแพ็กเกจ Room 2.x (androidx.room) ที่เน้น Kotlin Multiplatform (KMP)

เราจะคง API คำอธิบายประกอบหลักไว้เช่นเดิมพร้อมกับคอมโพเนนต์หลัก ดังนี้

คลาส Abstract ที่ขยาย androidx.room3.RoomDatabase และมีคำอธิบายประกอบ ด้วย @Database คือจุดแรกเข้าสำหรับเครื่องมือประมวลผลคำอธิบายประกอบของ Room
การประกาศฐานข้อมูลมีคลาสข้อมูลอย่างน้อย 1 รายการที่อธิบายสคีมาของฐานข้อมูล และมีคำอธิบายประกอบด้วย @Entity
การดำเนินการฐานข้อมูลจะกำหนดไว้ในประกาศ @Dao ที่มีฟังก์ชันการค้นหา ซึ่งกำหนดคำสั่ง SQL ผ่านคำอธิบายประกอบ @Query
ในเวลาเรียกใช้ คุณจะรับการติดตั้งใช้งานฐานข้อมูลได้ผ่าน RoomDatabase.Builder ซึ่งใช้ในการกำหนดค่าฐานข้อมูลด้วย

เอกสารประกอบส่วนใหญ่ในคำแนะนำบันทึกข้อมูลในฐานข้อมูลของเครื่องโดยใช้ Room ยังคง เกี่ยวข้องกับ Room 3.0

การเปลี่ยนแปลงที่สำคัญใน Room 2.x มีดังนี้

แพ็กเกจใหม่ androidx.room3
เราไม่รองรับ SupportSQLite API อีกต่อไป เว้นแต่คุณจะใช้ androidx.room3:room3-sqlite-wrapper
ตอนนี้การดำเนินการฐานข้อมูลทั้งหมดเป็นไปตาม Coroutine API
การสร้างโค้ด Kotlin เท่านั้น
ต้องใช้ Kotlin Symbol Processing (KSP)

นอกจากการเปลี่ยนแปลงที่ทำให้ใช้งานร่วมกันไม่ได้แล้ว Room 3.0 ยังมีฟังก์ชันใหม่ๆ เมื่อเทียบกับเวอร์ชัน 2.x ดังนี้

การรองรับ JS และ WasmJS
ประเภทการคืนค่า DAO ที่กำหนดเอง

แพ็กเกจใหม่

Room 3.0 จะอยู่ในแพ็กเกจใหม่ ซึ่งหมายความว่าจะมีกลุ่ม Maven ใหม่และรหัสอาร์ติแฟกต์ใหม่ด้วย เพื่อป้องกันปัญหาความเข้ากันได้กับการติดตั้งใช้งาน Room 2.x ที่มีอยู่และสำหรับไลบรารีที่มีการอ้างอิงแบบทรานซิทีฟไปยัง Room (เช่น WorkManager) เช่น androidx.room:room-runtime เปลี่ยนเป็น androidx.room3:room3-runtime และชั้นเรียน เช่น androidx.room.RoomDatabase จะอยู่ที่ androidx.room3.RoomDatabase

ไม่มี API ของ SupportSQLite

Room 3.0 ได้รับการสนับสนุนอย่างเต็มที่จาก SQLiteDriver APIs และไม่ได้อ้างอิงถึงประเภท SupportSQLite เช่น SupportSQLiteDatabase หรือประเภท Android เช่น Cursor อีกต่อไป นี่เป็นการเปลี่ยนแปลงที่สำคัญที่สุดระหว่าง Room 3.0 กับ 2.x เนื่องจากมีการนำ RoomDatabase API ที่จำลอง SupportSQLiteDatabase ออกพร้อมกับ API ที่ใช้รับ SupportSQLiteOpenHelper ตอนนี้ต้องมี SQLiteDriver เพื่อสร้าง RoomDatabase

เช่น API สำหรับการดำเนินการฐานข้อมูลโดยตรงจะถูกแทนที่ด้วยไดรเวอร์ ที่เทียบเท่า

// 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 ที่มี SupportSQLiteDatabase เป็นอาร์กิวเมนต์ด้วย API ที่เทียบเท่าซึ่งมี SQLiteConnection เป็นอาร์กิวเมนต์ ซึ่งเป็นฟังก์ชันเรียกกลับของการย้ายข้อมูล เช่น Migration.onMigrate() และ AutoMigrationSpec.onPostMigrate() รวมถึงการเรียกกลับของฐานข้อมูล เช่น RoomDatabase.Callback.onCreate(), RoomDatabase.Callback.onOpen() เป็นต้น

หากใช้ Room ในโปรเจ็กต์ KMP การย้ายข้อมูลไปยัง 3.0 จะง่ายกว่าเนื่องจากส่วนใหญ่เกี่ยวข้องกับการอัปเดตการอ้างอิงการนำเข้า ไม่เช่นนั้นจะใช้กลยุทธ์การย้ายข้อมูลเดียวกันจาก Room ใน Android เท่านั้นไปยัง KMP โปรดดูคู่มือการย้ายข้อมูล Room KMP

SupportSQLite Wrapper

Room 3.x จะเก็บ Wrapper SupportSQLite ที่สร้างใน 2.x ไว้เพื่ออำนวยความสะดวกในการย้ายข้อมูล และตอนนี้อยู่ในอาร์ติแฟกต์ใหม่ androidx.room3:room3-sqlite-wrapper API ความเข้ากันได้ช่วยให้คุณแปลง RoomDatabase เป็น SupportSQLiteDatabase ได้ การเรียกใช้ roomDatabase.openHelper.writableDatabase สามารถแทนที่ด้วย roomDatabase.getSupportWrapper()

Kotlin และ Coroutines First

Room 3.0 จะสร้างเฉพาะโค้ด Kotlin และเป็นเพียง ตัวประมวลผลสัญลักษณ์ Kotlin (KSP) เพื่อพัฒนาไลบรารีให้ดียิ่งขึ้น เมื่อเทียบกับ Room 2.x แล้ว Room 3.0 จะไม่มีการสร้างโค้ด Java และการกำหนดค่า Annotation Processor ผ่าน KAPT หรือ JavaAP จะไม่สามารถทำได้อีกต่อไป โปรดทราบว่า KSP สามารถประมวลผลแหล่งที่มาของ Java และ คอมไพเลอร์ Room จะสร้างโค้ดสำหรับฐานข้อมูล เอนทิตี หรือ DAO ที่มีการประกาศแหล่งที่มา ใน Java ขอแนะนำให้มีโปรเจ็กต์แบบหลายโมดูลซึ่งมีการใช้งาน Room อยู่รวมกัน และสามารถใช้ปลั๊กอิน Kotlin Gradle และ KSP ได้โดยไม่ส่งผลต่อส่วนอื่นๆ ของโค้ดเบส

Room 3.0 ยังกำหนดให้ใช้ Coroutines และโดยเฉพาะอย่างยิ่ง ฟังก์ชัน DAO ต้องระงับการทำงานเว้นแต่จะแสดงผลประเภทรีแอกทีฟ เช่น Flow หรือประเภทการแสดงผล DAO ที่กำหนดเอง นอกจากนี้ API ของ Room ที่ใช้ดำเนินการกับฐานข้อมูล ยังเป็นฟังก์ชันที่ระงับได้ด้วย เช่น RoomDatabase.useReaderConnection และ RoomDatabase.useWriterConnection

ซึ่งต่างจาก Room 2.x ที่ไม่สามารถกำหนดค่า RoomDatabase ด้วย Executor ได้อีกต่อไป แต่จะใช้ CoroutineContext พร้อมกับ Dispatcher แทนได้ ผ่านเครื่องมือสร้างของฐานข้อมูล

InvalidationTracker API ใน Room 3.0 Flow InvalidationTracker.Observer จะถูกนำออกพร้อมกับ API ที่เกี่ยวข้อง addObserver และ removeObserver กลไกในการตอบสนองต่อการดำเนินการกับฐานข้อมูล คือผ่าน Coroutine Flow ที่สร้างได้ผ่าน createFlow() API ใน InvalidationTracker

ตัวอย่างการใช้งาน

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

การสนับสนุนทางเว็บ

การเปิดตัว Room 3.0 เพิ่ม JavaScript และ WasmJs เป็นเป้าหมาย KMP เมื่อรวมเข้ากับ การเปิดตัวอินเทอร์เฟซ SQLiteDriver (androidx.sqlite:sqlite) ที่ กำหนดเป้าหมายไปยัง JavaScript และ WasmJs ด้วย รวมถึงไดรเวอร์ใหม่ WebWorkerSQLiteDriver ที่อยู่ในอาร์ติแฟกต์ใหม่ androidx.sqlite:sqlite-web คุณจะใช้ Room ในโค้ดทั่วไปที่กำหนดเป้าหมายไปยังแพลตฟอร์ม KMP หลักๆ ทั้งหมดได้

เนื่องจากแพลตฟอร์มเว็บทำงานแบบไม่พร้อมกัน ตอนนี้ Room API ที่รับ SQLiteStatement เป็นอาร์กิวเมนต์จึงเป็นฟังก์ชันที่ระงับ ตัวอย่างฟังก์ชันเหล่านี้ ได้แก่ Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() และอื่นๆ ใน API ของไดรเวอร์ API แบบไม่พร้อมกันจะใช้กันทั่วไปในทุกแพลตฟอร์ม และ API แบบพร้อมกันจะใช้กันทั่วไป สำหรับเป้าหมายที่ไม่ใช่เว็บ ดังนั้น โปรเจ็กต์ที่ไม่ได้กำหนดเป้าหมายเป็นเว็บจะใช้ API แบบซิงโครนัส (SQLiteDriver.open(), SQLiteConnection.prepare() และ SQLiteStatement.step()) ในโค้ดทั่วไปต่อไปได้ ในขณะเดียวกัน โปรเจ็กต์ที่กำหนดเป้าหมายเป็นเว็บเท่านั้นต้องใช้ API แบบไม่พร้อมกัน (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() และ SQLiteStatement.stepAsync())

เพื่อความสะดวก androidx.sqlite แพ็กเกจยังได้เพิ่มฟังก์ชันส่วนขยายระงับ ที่มีชื่อแบบซิงโครนัสของ API ที่กล่าวถึง (พร้อมส่วนเพิ่มเติม ของ SQLiteConnection.executeSQL) เราขอแนะนำให้ใช้ API เหล่านี้เมื่อโปรเจ็กต์ กำหนดเป้าหมายทั้งแพลตฟอร์มเว็บและที่ไม่ใช่เว็บ เนื่องจาก API เป็นการประกาศที่คาดการณ์ / เกิดขึ้นจริง ซึ่งจะเรียกตัวแปรที่ถูกต้องตามแพลตฟอร์ม ซึ่งเป็น API ที่รันไทม์ของ Room ใช้และเปิดใช้การใช้งานไดรเวอร์ในโค้ดทั่วไปสำหรับแพลตฟอร์มที่รองรับทั้งหมด

ตัวอย่างการใช้งาน

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 คือการติดตั้งใช้งาน SQLiteDriver ที่ สื่อสารกับ Web Worker เพื่อดำเนินการฐานข้อมูลนอกเธรดหลักและช่วยให้จัดเก็บ ฐานข้อมูลใน Origin Private File System (OPFS) ได้ หากต้องการสร้างอินสแตนซ์ของไดรเวอร์ ต้องมี Worker ที่ใช้โปรโตคอลการสื่อสารอย่างง่าย โดย โปรโตคอลจะอธิบายไว้ใน KDoc ของ WebWorkerSQLiteDriver

ปัจจุบัน WebWorkerSQLiteDriver ไม่ได้มาพร้อมกับ Worker เริ่มต้นที่ ใช้โปรโตคอลการสื่อสาร แต่ตัวอย่างเช่น ฐานโค้ด androidx มีการใช้งาน Worker ที่ใช้ในโปรเจ็กต์ได้ โดยใช้ WASM ของ SQLite และจัดเก็บฐานข้อมูลใน OPFS ระบบจะเผยแพร่ Worker ตัวอย่างเป็นแพ็กเกจ NPM ในเครื่อง และด้วยการรองรับการขึ้นต่อกันของ NPM ใน Kotlin จึงสร้างโมดูล KMP ขนาดเล็กเพื่อให้บริการ Worker ได้

ดูโปรเจ็กต์ GitHub ต่อไปนี้ ซึ่งแสดงการใช้งาน Web Worker ในเครื่องสำหรับ Room

เมื่อตั้งค่าผู้ปฏิบัติงานในโปรเจ็กต์แล้ว การกำหนดค่า Room for the Web จะคล้ายกับแพลตฟอร์มอื่นๆ ดังนี้

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 Driver เวอร์ชันในอนาคตอาจมี Worker เริ่มต้นที่เผยแพร่ใน NPM ซึ่งจะช่วยให้การตั้งค่าเว็บง่ายขึ้น

ประเภทการคืนค่า DAO ที่กำหนดเอง

การผสานรวมประเภทการคืนค่า DAO ต่างๆ เช่น การผสานรวมสำหรับ RxJava และ Paging ได้รับการแปลงให้ใช้ API ใหม่ใน Room 3.0 ที่เรียกว่าตัวแปลงประเภทการคืนค่า DAO ฟังก์ชันตัวแปลงประเภทการคืนค่าของ DAO (@DaoReturnTypeConverter) ช่วยให้ แปลงผลลัพธ์ของฟังก์ชัน DAO เป็นประเภทที่กำหนดเองซึ่งกำหนดโดย ฟังก์ชันที่มีคำอธิบายประกอบ ฟังก์ชันเหล่านี้ช่วยให้คุณเข้าร่วมในโค้ดที่ Room สร้างขึ้นได้ ซึ่งจะแปลงผลการค้นหาเป็นออบเจ็กต์ข้อมูล ต้องลงทะเบียนคลาสที่มีตัวแปลงประเภทการคืนค่า DAO ผ่าน คำอธิบายประกอบ @DaoReturnTypeConverters ในการประกาศ @Database หรือ @Dao

ตัวอย่างเช่น หากต้องการให้การค้นหา DAO แสดงผล PagingSource ตอนนี้คุณต้องลงทะเบียนคลาสตัวแปลง ที่อยู่ใน androidx.room3:room3-paging

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

ระบบได้ย้ายการผสานรวมที่มีอยู่ไปยังตัวแปลงประเภทการคืนค่า DAO แล้ว

ประเภทการแสดงผล	คลาส Converter	อาร์ติแฟกต์
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

เช่นเดียวกับตัวแปลงประเภทคอลัมน์ ตัวแปลงประเภทการคืนค่า DAO สามารถกำหนดได้โดยแอปพลิเคชัน เช่น แอปพลิเคชันอาจประกาศ @DaoReturnTypeConverter สำหรับประเภทเว็บ 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() }
    }
}

จากนั้นตัวแปลงข้างต้นจะอนุญาตให้ฟังก์ชันการค้นหา DAO แสดงผล Promise

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

@DaoReturnTypeConverter ฟังก์ชันมีข้อกำหนดบางอย่างเกี่ยวกับจำนวน พารามิเตอร์ที่ต้องมีและประเภทของพารามิเตอร์ พารามิเตอร์ที่เป็นไปได้มีดังนี้

db: RoomDatabase: (ไม่บังคับ) ให้สิทธิ์เข้าถึงRoomDatabase อินสแตนซ์ ซึ่งอาจมีประโยชน์ในการดำเนินการกับฐานข้อมูลเพิ่มเติม หรือเข้าถึงขอบเขตของโครูทีน
tableNames: Array<String>: (ไม่บังคับ) มีตารางที่เข้าถึงของคําค้นหา ซึ่งมีประโยชน์สําหรับการรองรับประเภทที่สังเกตได้ / โต้ตอบได้เมื่อรวมกับ InvalidationTracker.createFlow() API ของ Room
rawQuery: RoomRawQuery: (ไม่บังคับ) มีอินสแตนซ์ของ การค้นหาในรันไทม์ ซึ่งช่วยให้สามารถทำการเปลี่ยนรูปแบบต่างๆ เช่น กลยุทธ์ LIMIT / OFFSET ที่ใช้โดย PagingSourceDaoReturnTypeConverter
executeAndConvert: suspend () -> T: (ต้องระบุ) ฟังก์ชันที่สร้างขึ้นใน Room ซึ่งจะเรียกใช้การค้นหาและแยกวิเคราะห์ผลลัพธ์เป็นออบเจ็กต์ข้อมูล

ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อกำหนดในการสร้างตัวแปลงประเภทการคืนค่า DAO ได้ที่ KDoc ใน @DaoReturnTypeConverter API