บันทึกข้อมูลในฐานข้อมูลของเครื่องโดยใช้ Room   ซึ่งเป็นส่วนหนึ่งของ Android Jetpack.

ลองใช้กับ Kotlin Multiplatform
Kotlin Multiplatform ช่วยให้แชร์เลเยอร์ฐานข้อมูลกับแพลตฟอร์มอื่นๆ ได้ ดูวิธีตั้งค่าและใช้งานฐานข้อมูล Room ใน KMP
ตั้งค่าฐานข้อมูล Room สำหรับ KMP →

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

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

  • การตรวจสอบการค้นหา SQL ในเวลาคอมไพล์
  • คำอธิบายประกอบที่สะดวกซึ่งช่วยลดโค้ดเทมเพลตที่ต้องใช้บ่อยๆ และมีแนวโน้มที่จะเกิดข้อผิดพลาด
  • เส้นทางการย้ายข้อมูลฐานข้อมูลที่มีประสิทธิภาพ

เราขอแนะนำให้ใช้ Room แทนการใช้ API ของ SQLite โดยตรง

ตั้งค่า

หากต้องการใช้ Room ในแอป ให้เพิ่มทรัพยากร Dependency ต่อไปนี้ลงในไฟล์ build.gradle.kts ของโมดูล Room 3.0 ต้องใช้ KSP สำหรับการประมวลผลคำอธิบายประกอบ

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

คอมโพเนนต์หลัก

Room มีคอมโพเนนต์หลัก 3 รายการ ได้แก่

คลาสฐานข้อมูลจะมอบอินสแตนซ์ของ DAO ที่เชื่อมโยงกับฐานข้อมูลนั้นให้กับแอป ซึ่งแอปจะใช้ DAO เพื่อดึงข้อมูลจากฐานข้อมูลเป็นอินสแตนซ์ของออบเจ็กต์เอนทิตีข้อมูลที่เชื่อมโยง นอกจากนี้ แอปยังใช้เอนทิตีข้อมูลที่กำหนดเพื่ออัปเดตแถวจากตารางที่เกี่ยวข้อง หรือสร้างแถวใหม่เพื่อแทรกได้ด้วย รูปที่ 1 แสดงความสัมพันธ์ระหว่างคอมโพเนนต์ต่างๆ ของ Room

รูปที่ 1 แผนภาพสถาปัตยกรรมไลบรารี Room

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

ส่วนนี้จะแสดงตัวอย่างการใช้งานฐานข้อมูล Room ที่มีเอนทิตีข้อมูลเดียวและ DAO เดียว

เอนทิตีข้อมูล

โค้ดต่อไปนี้จะกำหนดเอนทิตีข้อมูล User โดยแต่ละอินสแตนซ์ของ User จะแสดงแถวในตาราง user ในฐานข้อมูลของแอป

@Entity
data class User(
    @PrimaryKey val uid: Int,
    @ColumnInfo(name = "first_name") val firstName: String,
    @ColumnInfo(name = "last_name") val lastName: String
)

ดูข้อมูลเพิ่มเติมเกี่ยวกับเอนทิตีข้อมูลใน Room ได้ที่ การกำหนดข้อมูลโดยใช้เอนทิตี Room

ออบเจ็กต์การเข้าถึงข้อมูล (DAO)

โค้ดต่อไปนี้จะกำหนด DAO ที่ชื่อ UserDao UserDao มีฟังก์ชันที่ส่วนอื่นๆ ของแอปใช้เพื่อโต้ตอบกับข้อมูลในตาราง user

@Dao
interface UserDao {
    @Query("SELECT * FROM user")
    suspend fun getAll(): List<User>

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    suspend fun loadAllByIds(userIds: IntArray): List<User>

    @Query(
        """
        SELECT * FROM user
        WHERE first_name LIKE :first AND last_name LIKE :last LIMIT 1
        """
    )
    suspend fun findByName(first: String, last: String): User

    @Insert
    suspend fun insertAll(vararg users: User)

    @Delete
    suspend fun delete(user: User)
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับ DAO ได้ที่ การเข้าถึงข้อมูลโดยใช้ Room DAO

ฐานข้อมูล

โค้ดต่อไปนี้จะกำหนดคลาส AppDatabase เพื่อเก็บฐานข้อมูล AppDatabase กำหนดการกำหนดค่าฐานข้อมูลและทำหน้าที่เป็นจุดเข้าใช้งานหลักของแอปสำหรับข้อมูลที่คงอยู่ คลาสฐานข้อมูลต้องเป็นไปตามเงื่อนไขต่อไปนี้

  • คลาสต้องมีคำอธิบายประกอบ a @Database ซึ่ง มีอาร์เรย์ entities ที่แสดงรายการเอนทิตีข้อมูลทั้งหมดที่เชื่อมโยงกับฐานข้อมูล
  • คลาสต้องเป็นคลาส Abstract ที่ขยาย RoomDatabase
  • สำหรับคลาส DAO แต่ละคลาสที่เชื่อมโยงกับฐานข้อมูล คลาสฐานข้อมูลต้องกำหนดฟังก์ชัน Abstract ที่ไม่มีอาร์กิวเมนต์และแสดงอินสแตนซ์ของคลาส DAO

@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

หมายเหตุ: หากแอปทำงานในกระบวนการเดียว คุณควรทำตาม รูปแบบการออกแบบ Singleton เมื่อสร้างอินสแตนซ์ออบเจ็กต์ AppDatabase เนื่องจากอินสแตนซ์ RoomDatabase แต่ละรายการมีค่าใช้จ่ายค่อนข้างสูง และคุณ ไม่ค่อยจำเป็นต้องเข้าถึงอินสแตนซ์หลายรายการภายในกระบวนการเดียว

หากแอปทำงานในหลายกระบวนการ ให้ใส่ enableMultiInstanceInvalidation() ในการเรียกใช้ตัวสร้างฐานข้อมูล วิธีนี้จะช่วยให้คุณล้างข้อมูลไฟล์ฐานข้อมูลที่แชร์ในกระบวนการหนึ่งได้เมื่อมีอินสแตนซ์ AppDatabase ในแต่ละกระบวนการ และการล้างข้อมูลนี้จะแพร่ไปยังอินสแตนซ์ของ AppDatabase ภายในกระบวนการอื่นๆ โดยอัตโนมัติ

การใช้งาน

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

val db =
    Room.databaseBuilder<AppDatabase>(applicationContext, "database-name")
        .setDriver(AndroidSQLiteDriver())
        .build()

จากนั้นคุณจะใช้ฟังก์ชัน Abstract จาก AppDatabase เพื่อรับอินสแตนซ์ของ DAO ได้ และใช้ฟังก์ชันจากอินสแตนซ์ DAO เพื่อโต้ตอบกับฐานข้อมูลได้

val userDao = db.userDao()
val users: List<User> = userDao.getAll()

แหล่งข้อมูลเพิ่มเติม

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Room ได้จากแหล่งข้อมูลเพิ่มเติมต่อไปนี้

ตัวอย่าง