ห้อง 3.0

  
ไลบรารี Room Persistence มีเลเยอร์การเปลี่ยนระดับนามธรรมเหนือ SQLite เพื่อให้เข้าถึงฐานข้อมูลได้อย่างมีประสิทธิภาพมากขึ้นในขณะที่ใช้ประโยชน์จากความสามารถทั้งหมดของ SQLite
อัปเดตล่าสุด รุ่นที่เสถียร รุ่นที่อาจได้รับการเผยแพร่ รุ่นเบต้า รุ่นอัลฟ่า
9 กันยายน 2026 3.0.3 - - 3.1.0-alpha01

การประกาศทรัพยากร 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 ทำงานได้ดีขึ้น โปรดแจ้งให้เราทราบหากพบปัญหาใหม่หรือมี ไอเดียในการปรับปรุงไลบรารีนี้ โปรดดูปัญหาที่มีอยู่ ในไลบรารีนี้ก่อนสร้างปัญหาใหม่ คุณสามารถโหวตปัญหาที่มีอยู่ได้โดย คลิกปุ่มดาว

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

ดูข้อมูลเพิ่มเติมได้ในเอกสารประกอบของ Issue Tracker

เวอร์ชัน 3.1

เวอร์ชัน 3.1.0-alpha01

9 กันยายน 2026

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

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

  • เพิ่ม setConnectionPoolTimeout(timeout: Duration) ใน RoomDatabase.Builder เพื่ออนุญาตให้กำหนดค่าการหมดเวลาของ Connection Pool (I24d07, b/404380974)
  • ตอนนี้คำอธิบายประกอบของ Room ต่อไปนี้มี AnnotationTarget.PROPERTY แล้ว ได้แก่ @ColumnInfo, @PrimaryKey, @Relation, @Embedded, @Ignore และ @ColumnTypeConverters การเปลี่ยนแปลง API นี้จะทำให้ห้องพักเป็น "เน้นพร็อพเพอร์ตี้" แทนที่จะเป็น "เน้นฟิลด์" ซึ่งหมายความว่า Room สามารถใช้พร็อพเพอร์ตี้ที่ไม่มีฟิลด์สำรองเป็นตัวแทนของคอลัมน์เอนทิตีหรือคอลัมน์ผลลัพธ์ของคลาสข้อมูลการค้นหาได้แล้ว พร็อพเพอร์ตี้ต้องยังมี Getter ที่ใช้ได้และ Setter ที่ใช้ได้ หรือเป็นส่วนหนึ่งของเครื่องมือสร้างหลักเพื่อให้ Room ใช้พร็อพเพอร์ตี้เหล่านั้นสำหรับฟังก์ชัน DAO ได้ (I72058, b/438041176, b/521861812)

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

  • แก้ไขปัญหาบนเว็บและการระงับไดรเวอร์ที่การยกเลิกโครูทีนระหว่างธุรกรรมอาจทำให้ฐานข้อมูลและการเชื่อมต่ออยู่ในสถานะที่ไม่ดี ซึ่งจะทำให้ใช้งานต่อไปไม่ได้ (If75c0, b/549860940)
  • รองรับการobjectติดตั้งใช้งานAutoMigrationSpec Kotlin (Id4077, b/215012591)
  • แก้ไขการเกิดปัญหาซ้ำที่จะทำให้ Room ส่ง IllegalMonitorStateException เมื่อใช้ฟังก์ชัน DAO ของ Wrapper @Transaction (I996d9, b/543285472, b/553140228)
  • เพิ่มการรองรับตัวแปลงประเภทคอลัมน์ในตัวสำหรับ kotlin.uuid.Uuid ใน Room (Icca77, b/525093264)
  • ตอนนี้เครื่องมือสร้างโค้ด Kotlin ของ Room จะระงับ OPT_IN_USAGE_ERROR และ OPT_IN_USAGE ในคลาส _Impl ที่สร้างขึ้น ทำให้ DAO และเอนทิตีใช้ประเภทที่ใส่คำอธิบายประกอบ @RequiresOptIn (เช่น kotlin.uuid.Uuid) ได้โดยไม่ต้องใช้ -opt-in ใน freeCompilerArgs (I013bf, b/410607888)
  • ตอนนี้การค้นหาการระงับห้องและการดำเนินการติดตามการลบล้างจะแสดง IllegalStateException เมื่อเรียกใช้หลังจากปิดฐานข้อมูลแล้ว (I5755a, b/543076356)
  • แก้ไขภาวะหยุดชะงักที่อาจเกิดขึ้นใน@Transactionฟังก์ชันระงับของ Wrapper DAO ซึ่งจะสลับบริบทและมีการกำหนดค่า AndroidSQLiteDriver (886ac5, b/543285472)
  • แก้ไข println() ที่ไม่จำเป็นระหว่างการประมวลผล ขอขอบคุณ Simon Marquis (b/532893031)
  • แก้ไขปัญหาเกี่ยวกับการใช้งานฐานข้อมูลอื่นๆ ภายในธุรกรรมของฐานข้อมูลอื่นที่ผสมกันจนทำให้เกิดลักษณะการทำงานที่ไม่แน่นอน (b/437068912)

เวอร์ชัน 3.0

เวอร์ชัน 3.0.3

9 กันยายน 2026

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

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

  • แก้ไขการเกิดปัญหาซ้ำที่จะทำให้ Room ส่ง IllegalMonitorStateException เมื่อใช้ฟังก์ชัน DAO ของ Wrapper @Transaction (I996d9, b/543285472, b/553140228)
  • แก้ไขปัญหาบนเว็บและการระงับไดรเวอร์ที่การยกเลิกโครูทีนระหว่างธุรกรรมอาจทำให้ฐานข้อมูลและการเชื่อมต่ออยู่ในสถานะที่ไม่ดี ซึ่งจะทำให้ใช้งานต่อไปไม่ได้ (If75c0, b/549860940)

เวอร์ชัน 3.0.2

26 สิงหาคม 2026

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

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

  • ตอนนี้การค้นหาการระงับห้องและการดำเนินการติดตามการลบล้างจะแสดง IllegalStateException เมื่อเรียกใช้หลังจากปิดฐานข้อมูลแล้ว (I5755a, b/543076356)
  • แก้ไขภาวะหยุดชะงักที่อาจเกิดขึ้นใน@Transactionฟังก์ชันระงับของ Wrapper DAO ซึ่งจะสลับบริบทและมีการกำหนดค่า AndroidSQLiteDriver (886ac5, b/543285472)

เวอร์ชัน 3.0.1

29 กรกฎาคม 2026

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

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

  • แก้ไข println() ที่ไม่จำเป็นระหว่างการประมวลผล ขอขอบคุณ Simon Marquis (b/532893031)
  • แก้ไขปัญหาเกี่ยวกับการใช้งานฐานข้อมูลอื่นๆ ภายในธุรกรรมของฐานข้อมูลอื่นที่ผสมกันจนทำให้เกิดลักษณะการทำงานที่ไม่แน่นอน (b/437068912)

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

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

ประเภทการแสดงผล คลาสตัวแปลง อาร์ติแฟกต์
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 ซึ่งเมื่อตั้งค่าเป็นจริง จะสร้างตาราง 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)
  • พยายามแก้ไข (อีกครั้ง) ข้อผิดพลาด "เมธอดใหญ่เกินไป" ที่เกิดขึ้นเนื่องจาก 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 เป็นแบบสาธารณะเพื่อหลีกเลี่ยงประกาศเตือนของเครื่องมือวิเคราะห์ซอร์สโค้ด เมื่อมีการอ้างอิงเครื่องมือสร้างในการประกาศ @ฐานข้อมูล (I9bac2, b/494722261)
  • เพิ่มเวอร์ชันของ Room.inMemoryDatabaseBuilder และ Room.databaseBuilder ที่ไม่ต้องใช้บริบท Android ความจำเป็นในการใช้บริบทลดลงอย่างมากใน 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ระบบจะถอนการอ้างสิทธิ์

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

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

  • คลาสแอบสแทรกต์ที่ขยาย 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 ที่กำหนดเอง

แพ็กเกจใหม่

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 และไม่สามารถกำหนดค่าโปรเซสเซอร์สำหรับคำอธิบายประกอบผ่าน 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 และ เพจจิ้ง ได้รับการแปลงให้ใช้ 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 แล้ว

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