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

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

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

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

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

ตั้งค่า

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

Kotlin

dependencies {
    val room_version = "2.6.1"

    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.6.1"

    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 ที่มีเอนทิตีข้อมูลเดียวและ 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

บล็อก