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

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

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

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

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

ด้วยเหตุผลเหล่านี้ เราจึงขอแนะนำให้คุณใช้ Room แทนการใช้ SQLite API โดยตรง

ตั้งค่า

หากต้องการใช้ Room ในแอป ให้เพิ่มทรัพยากร Dependency ต่อไปนี้ลงในไฟล์ build.gradle ของแอป

Kotlin

dependencies {
    val room_version = "2.7.2"

    implementation("androidx.room:room-runtime:$room_version")

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See Add the KSP plugin to your project
    ksp("androidx.room:room-compiler:$room_version")

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor("androidx.room:room-compiler:$room_version")

    // optional - Kotlin Extensions and Coroutines support for Room
    implementation("androidx.room:room-ktx:$room_version")

    // optional - RxJava2 support for Room
    implementation("androidx.room:room-rxjava2:$room_version")

    // optional - RxJava3 support for Room
    implementation("androidx.room:room-rxjava3:$room_version")

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation("androidx.room:room-guava:$room_version")

    // optional - Test helpers
    testImplementation("androidx.room:room-testing:$room_version")

    // optional - Paging 3 Integration
    implementation("androidx.room:room-paging:$room_version")
}

Groovy

dependencies {
    def room_version = "2.7.2"

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

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See KSP Quickstart to add KSP to your build
    ksp "androidx.room:room-compiler:$room_version"

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor "androidx.room:room-compiler:$room_version"

    // optional - RxJava2 support for Room
    implementation "androidx.room:room-rxjava2:$room_version"

    // optional - RxJava3 support for Room
    implementation "androidx.room:room-rxjava3:$room_version"

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation "androidx.room:room-guava:$room_version"

    // optional - Test helpers
    testImplementation "androidx.room:room-testing:$room_version"

    // optional - Paging 3 Integration
    implementation "androidx.room:room-paging:$room_version"
}

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

Room มีองค์ประกอบหลัก 3 อย่าง ได้แก่

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

รูปที่ 1 แผนภาพสถาปัตยกรรมของ Room Library

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

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

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

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

Kotlin

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

Java

@Entity
public class User {
    @PrimaryKey
    public int uid;

    @ColumnInfo(name = "first_name")
    public String firstName;

    @ColumnInfo(name = "last_name")
    public String lastName;
}

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

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

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

Kotlin

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

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

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

    @Insert
    fun insertAll(vararg users: User)

    @Delete
    fun delete(user: User)
}

Java

@Dao
public interface UserDao {
    @Query("SELECT * FROM user")
    List<User> getAll();

    @Query("SELECT * FROM user WHERE uid IN (:userIds)")
    List<User> loadAllByIds(int[] userIds);

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

    @Insert
    void insertAll(User... users);

    @Delete
    void delete(User user);
}

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

ฐานข้อมูล

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

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

Kotlin

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

Java

@Database(entities = {User.class}, version = 1)
public abstract class AppDatabase extends RoomDatabase {
    public abstract UserDao userDao();
}

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

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

การใช้งาน

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

Kotlin

val db = Room.databaseBuilder(
            applicationContext,
            AppDatabase::class.java, "database-name"
        ).build()

Java

AppDatabase db = Room.databaseBuilder(getApplicationContext(),
        AppDatabase.class, "database-name").build();

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

Kotlin

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

Java

UserDao userDao = db.userDao();
List<User> users = userDao.getAll();

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

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

ตัวอย่าง

Codelabs

บล็อก