Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

ห้อง 3.0

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

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

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

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

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

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 ได้ที่เอกสารประกอบฉบับย่อสำหรับ KSP

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

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

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

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

ดึงดูด

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

Kotlin

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

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

ดึงดูด

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

1 กรกฎาคม 2026

ระบบจะถอนการอ้างสิทธิ์androidx.room3:room3-*:3.0.0 เวอร์ชัน 3.0.0 มีการเปลี่ยนแปลงเหล่านี้

ฟีเจอร์หลักของเวอร์ชัน 3.0.0

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 (KSP)

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

การรองรับ JS และ WasmJS
ประเภทการคืนค่า DAO ที่กำหนดเอง
รองรับ FTS5 ผ่าน@Fts5คำอธิบายประกอบ
การรองรับค่าพารามิเตอร์เริ่มต้นของ Kotlin
PrimaryKey.algorihtm เพื่อระบุอัลกอริทึมการสร้างคีย์หลัก
ความสามารถในการสร้างตาราง "WITHOUT ROWID"
คอลัมน์ความสัมพันธ์แบบผสมที่มี @Relation

แพ็กเกจใหม่

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

ไม่มี SupportSQLite API

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 Plugin และ 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 ที่รันไทม์ของห้องใช้และเปิดใช้การใช้งานไดรเวอร์ในโค้ดทั่วไปสำหรับแพลตฟอร์มที่รองรับทั้งหมด

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

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 ที่ใช้โปรโตคอลการสื่อสารอย่างง่าย โดย โปรโตคอลจะอธิบายไว้ใน WebWorkerSQLiteDriver KDoc

ปัจจุบัน 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

เวอร์ชัน 3.0.0-rc01

17 มิถุนายน 2026

ระบบจะถอนการอ้างสิทธิ์androidx.room3:room3-*:3.0.0-rc01 เวอร์ชัน 3.0.0-rc01 มีการคอมมิตเหล่านี้

ฟีเจอร์ใหม่

เพิ่มการรองรับพารามิเตอร์ที่มีค่าเริ่มต้นในคลาสข้อมูลที่ใช้ในผลการค้นหา DAO พร็อพเพอร์ตี้ที่แสดงถึงคอลัมน์และเป็นส่วนหนึ่งของตัวสร้างที่มีค่าเริ่มต้นจะถือว่าเป็นพร็อพเพอร์ตี้ที่ไม่บังคับ และระบบจะไม่กำหนดให้ต้องมีคอลัมน์ในผลลัพธ์สำหรับพร็อพเพอร์ตี้นั้น (34279a, b/70762008, b/193531601)

การเปลี่ยนแปลง API

เปลี่ยนชื่อ @TypeConverter เป็น @ColumnTypeConverter เพื่อให้แยกความแตกต่างของขอบเขต Conversion ได้ดีขึ้น และเพื่อให้สอดคล้องกับ @DaoReturnTypeConverter (I24420, b/438041176)
เพิ่ม API สำหรับประเภทการคืนค่า DAO ที่กำหนดเองที่ระบุ @ProvidedDaoReturnTypeConveter (I2a8ad, b/517485682)
เพิ่มพร็อพเพอร์ตี้ PrimaryKey.algorihtm เพื่อระบุอัลกอริทึมการสร้างคีย์หลักเมื่อตั้งค่า PrimaryKey.autoGenerate เป็นจริง (I57944, b/70053837)

เวอร์ชัน 3.0.0-alpha06

3 มิถุนายน 2026

ระบบจะถอนการอ้างสิทธิ์androidx.room3:room3-*:3.0.0-alpha06 เวอร์ชัน 3.0.0-alpha06 มีการเปลี่ยนแปลงเหล่านี้

การเปลี่ยนแปลง API

เพิ่มพร็อพเพอร์ตี้คำอธิบายประกอบใหม่ใน @Entity ชื่อ withoutRowId ซึ่งเมื่อตั้งค่าเป็น true จะสร้างตาราง SQLite สำรองโดยใช้ตัวเลือก WITHOUT ROWID (Idb48e, b/472790803)

เวอร์ชัน 3.0.0-alpha05

19 พฤษภาคม 2026

ระบบจะถอนการอ้างสิทธิ์androidx.room3:room3-*:3.0.0-alpha05 เวอร์ชัน 3.0.0-alpha05 มีการเปลี่ยนแปลงเหล่านี้

การเปลี่ยนแปลง API

อัปเดต @Relation และ @Junction เพื่อให้พร็อพเพอร์ตี้ parentColumns และ entityColumns เป็นอาร์เรย์ของชื่อคอลัมน์ที่จะใช้เป็นคีย์ในการแก้ความสัมพันธ์ ซึ่งจะรองรับคีย์ความสัมพันธ์แบบรวม (I92196, b/64247765)

เวอร์ชัน 3.0.0-alpha04

6 พฤษภาคม 2026

ระบบจะถอนการอ้างสิทธิ์androidx.room3:room3-*:3.0.0-alpha04 เวอร์ชัน 3.0.0-alpha04 มีการเปลี่ยนแปลงเหล่านี้

การเปลี่ยนแปลง API

เพิ่ม API เพื่อกำหนดค่า Connection Pool ของ Room ฟังก์ชันตัวสร้าง setSingleConnectionPool() และ setMultipleConnectionPool() สามารถใช้เพื่อควบคุมจำนวนการเชื่อมต่อสูงสุดที่ Room จะเปิดไปยังฐานข้อมูลได้ (I9700d, b/438041176, b/432820350)
นำ DatabaseConfiguration ของห้องออกจาก API สาธารณะเนื่องจากไม่มี API สาธารณะอื่นอ้างอิงการกำหนดค่า (I5f1e9, b/438041176)

การแก้ไขข้อบกพร่อง

จำกัดเป้าหมายเว็บให้ใช้ Connection Pool เดียวเพื่อหลีกเลี่ยงปัญหา "ล็อกฐานข้อมูล" ที่เกิดขึ้นกับ OPFS (b/496255935)
พยายามแก้ไข (อีกครั้ง) ข้อผิดพลาด "Method too large" ที่เกิดขึ้นเนื่องจาก Room สร้าง onValidateSchema ที่มีขนาดใหญ่เกินไป ฟังก์ชันจะแยกตามจำนวนคำสั่ง แต่การวัดผลจะไม่แม่นยำ หากยังคงพบข้อผิดพลาดนี้ คุณสามารถปรับจำนวนรายการที่ Room จะนับรวมในการแยกรายได้ผ่านตัวเลือกโปรแกรมประมวลผลคำอธิบายประกอบ room.validationSplitSize ปัจจุบันค่าเริ่มต้นตั้งไว้ที่ 300 รายการ ดังนั้นให้ใช้ตัวเลขที่ต่ำกว่าหากปัญหายังคงอยู่ (b/493708172)

เวอร์ชัน 3.0.0-alpha03

8 เมษายน 2026

ระบบจะถอนการอ้างสิทธิ์androidx.room3:room3-*:3.0.0-alpha03 เวอร์ชัน 3.0.0-alpha03 มีคอมมิตเหล่านี้

การเปลี่ยนแปลง API

ทำให้ตัวสร้างแบบไม่มีอาร์กิวเมนต์ของ RoomDatabase เป็นแบบสาธารณะเพื่อหลีกเลี่ยงคำเตือนของ Lint เมื่อมีการอ้างอิงตัวสร้างในการประกาศ @Database (I9bac2, b/494722261)
เพิ่มเวอร์ชันของ Room.inMemoryDatabaseBuilder และ Room.databaseBuilder ที่ไม่ต้องใช้บริบท Android ความจำเป็นในการใช้ Context ลดลงอย่างมากใน Room 3.0 ดังนั้นการทำให้เป็นค่าที่ไม่บังคับสำหรับ Builder จึงช่วยให้สร้างฐานข้อมูลในหน่วยความจำในโค้ดทั่วไปได้ง่ายขึ้น (I5d502, b/438041176)

การแก้ไขข้อบกพร่อง

แก้ไขข้อผิดพลาด "โค้ดมีขนาดใหญ่เกินไป" ในโค้ดที่สร้างขึ้นของ JVM และ Android เมื่อเนื้อหาของฟังก์ชัน onValidateSchema มีขนาดใหญ่เกินไป (b/493708172)

เวอร์ชัน 3.0.0-alpha02

25 มีนาคม 2026

ระบบจะถอนการอ้างสิทธิ์androidx.room3:room3-*:3.0.0-alpha02 เวอร์ชัน 3.0.0-alpha02 มีคอมมิตเหล่านี้

ฟีเจอร์ใหม่

การรองรับ FTS5: เพิ่มการรองรับ FTS5 ลงใน Room ผ่าน@Fts5 ซึ่งรวมถึงค่าคงที่ใหม่สำหรับโทเค็นไนเซอร์ FTS5 (TOKENIZER_ASCII และ TOKENIZER_TRIGRAM) และ Enum สำหรับตัวเลือก FTS "detail" (FULL, COLUMN และ NONE) (I90934, b/146824830)
เป้าหมายการเรียกหน้าในห้อง: เพิ่มเป้าหมาย js, wasmJs, tvOS และ watchOS ไปยัง room3-paging (Icffd3, b/432783733)

การเปลี่ยนแปลง API

หลายแพลตฟอร์ม clearAllTables(): ทั่วไป clearAllTables() ทำให้พร้อมใช้งานในทุกแพลตฟอร์ม นอกจากนี้ยังแปลงเป็นฟังก์ชัน suspend ด้วย (I434ae, b/322846465)
การย้ายข้อมูลที่ทําลายข้อมูล: เพิ่มค่าพารามิเตอร์เริ่มต้นลงใน dropAllTables ใน API ของ fallbackToDestructiveMigration (Ica88b, b/438041176)
การเปลี่ยนแปลง API เวอร์ชันทดลอง:
1. ย้าย @ExperimentalRoomApi ไปยัง room-common เพื่อให้ทำเครื่องหมาย API ที่อิงตามคำอธิบายประกอบว่าเป็นการทดลองได้
2. เพิ่ม RoomWarning เวอร์ชันทดลองเพื่อยกเลิกข้อกำหนดสำหรับ @ConstructedBy ในการประกาศฐานข้อมูล Room ในกรณีนี้ ระบบจะไม่สร้าง DatabaseConstructor และต้องมีการติดตั้งใช้งานจากโรงงานผ่าน DatabaseBuilder (If5443)

การแก้ไขข้อบกพร่อง

แหล่งที่มาของการแบ่งหน้า: อัปเดต PagingSourceDaoReturnTypeConverter เพื่อระบุอย่างถูกต้องว่าฟังก์ชันการแปลงมีไว้สำหรับคำค้นหา READ (I3b067, b/139872302)

เวอร์ชัน 3.0.0-alpha01

11 มีนาคม 2026

ระบบจะถอนการอ้างสิทธิ์androidx.room3:room3-*:3.0.0-alpha01

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

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

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

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

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

แพ็กเกจใหม่

ไม่มี SupportSQLite API

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

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

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

SupportSQLite Wrapper

Kotlin และ Coroutines First

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

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

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

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

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 ที่ใช้โปรโตคอลการสื่อสารอย่างง่าย โดย โปรโตคอลจะอธิบายไว้ใน WebWorkerSQLiteDriver KDoc

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

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

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

@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

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

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