Thư viện lưu trữ dữ liệu Room cung cấp một lớp trừu tượng qua SQLite để mang lại khả năng truy cập cơ sở dữ liệu mạnh mẽ hơn, đồng thời khai thác toàn bộ sức mạnh của SQLite. Trang này tập trung vào việc sử dụng Room trong các dự án Kotlin Multiplatform (KMP). Để biết thêm thông tin về cách sử dụng Room, hãy xem bài viết Lưu dữ liệu trong cơ sở dữ liệu cục bộ bằng Room hoặc mẫu chính thức của chúng tôi.
Thiết lập phần phụ thuộc
Để thiết lập Room trong dự án KMP, hãy thêm các phần phụ thuộc cho cấu phần phần mềm trong tệp build.gradle.kts cho mô-đun KMP.
Xác định các phần phụ thuộc trong tệp libs.versions.toml:
[versions]
room3 = "3.1.0-alpha03"
sqlite = "2.7.1"
ksp = "<kotlinCompatibleKspVersion>"
[libraries]
androidx-sqlite-bundled = { module = "androidx.sqlite:sqlite-bundled", version.ref = "sqlite" }
androidx-room3-runtime = { module = "androidx.room3:room3-runtime", version.ref = "room3" }
androidx-room3-compiler = { module = "androidx.room3:room3-compiler", version.ref = "room3" }
# Optional SQLite Wrapper
androidx-room3-sqlite-wrapper = { module = "androidx.room3:room3-sqlite-wrapper", version.ref = "room3" }
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
androidx-room3 = { id = "androidx.room3", version.ref = "room3" }
Thêm trình bổ trợ Room cho Gradle để định cấu hình giản đồ Room và trình bổ trợ KSP.
plugins {
alias(libs.plugins.ksp)
alias(libs.plugins.androidx.room3)
}
Thêm phần phụ thuộc thời gian chạy Room và thư viện SQLite đi kèm:
commonMain.dependencies {
implementation(libs.androidx.room3.runtime)
implementation(libs.androidx.sqlite.bundled)
}
// Optional when using Room SQLite Wrapper
androidMain.dependencies {
implementation(libs.androidx.room3.sqlite.wrapper)
}
Thêm các phần phụ thuộc KSP vào khối dependencies gốc. Bạn cần thêm tất cả mục tiêu mà ứng dụng của bạn sử dụng. Để biết thêm thông tin, hãy xem bài viết KSP với Kotlin Multiplatform.
dependencies {
add("kspAndroid", libs.androidx.room3.compiler)
add("kspIosSimulatorArm64", libs.androidx.room3.compiler)
add("kspIosX64", libs.androidx.room3.compiler)
add("kspIosArm64", libs.androidx.room3.compiler)
// Add any other platform target you use in your project, for example kspDesktop
}
Xác định thư mục giản đồ Room. Để biết thêm thông tin, hãy xem bài viết Đặt vị trí giản đồ bằng trình bổ trợ Room cho Gradle.
room {
schemaDirectory("$projectDir/schemas")
}
Xác định các lớp cơ sở dữ liệu
Bạn cần tạo một lớp cơ sở dữ liệu có chú thích bằng @Database cùng với DAO và các thực thể bên trong nhóm tài nguyên chung của mô-đun KMP dùng chung. Việc đặt các lớp này vào các nguồn chung sẽ cho phép chia sẻ các lớp này trên tất cả các nền tảng mục tiêu.
// shared/src/commonMain/kotlin/Database.kt @Database(entities = [TodoEntity::class], version = 1) @ConstructedBy(AppDatabaseConstructor::class) abstract class AppDatabase : RoomDatabase() { abstract fun getDao(): TodoDao } // The Room compiler generates the `actual` implementations. @Suppress("KotlinNoActualForExpect") expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase> { override fun initialize(): AppDatabase }
Khi bạn khai báo một đối tượng expect bằng giao diện RoomDatabaseConstructor, trình biên dịch Room sẽ tạo các phương thức triển khai actual. Android Studio có thể đưa ra cảnh báo sau đây mà bạn có thể
loại bỏ bằng @Suppress("KotlinNoActualForExpect"):
Expected object 'AppDatabaseConstructor' has no actual declaration in module`
Tiếp theo, hãy xác định một giao diện DAO mới hoặc di chuyển một giao diện hiện có sang commonMain:
// shared/src/commonMain/kotlin/TodoDao.kt @Dao interface TodoDao { @Insert suspend fun insert(item: TodoEntity) @Query("SELECT count(*) FROM TodoEntity") suspend fun count(): Int @Query("SELECT * FROM TodoEntity") fun getAllAsFlow(): Flow<List<TodoEntity>> }
Xác định hoặc di chuyển thực thể sang commonMain:
// shared/src/commonMain/kotlin/TodoEntity.kt @Entity data class TodoEntity( @PrimaryKey(autoGenerate = true) val id: Long = 0, val title: String, val content: String )
Tạo trình tạo cơ sở dữ liệu theo nền tảng cụ thể
Bạn cần xác định một trình tạo cơ sở dữ liệu để tạo thực thể Room trên mỗi nền tảng. Đây là phần duy nhất của API mà bạn phải xác định trong các nhóm tài nguyên dành riêng cho nền tảng, do sự khác biệt về API hệ thống tệp.
Android
Trên Android, bạn thường lấy vị trí cơ sở dữ liệu bằng API Context.getDatabasePath. Để tạo phiên bản thể hiện của cơ sở dữ liệu, hãy chỉ định Context và đường dẫn cơ sở dữ liệu.
// shared/src/androidMain/kotlin/Database.android.kt fun getDatabaseBuilder(context: Context): RoomDatabase.Builder<AppDatabase> { val appContext = context.applicationContext val dbFile = appContext.getDatabasePath("my_room.db") return Room.databaseBuilder<AppDatabase>( context = appContext, name = dbFile.absolutePath ) }
iOS
Để tạo thực thể cơ sở dữ liệu trên iOS, hãy cung cấp đường dẫn cơ sở dữ liệu bằng cách sử dụng
NSFileManager, thường nằm trong NSDocumentDirectory.
// shared/src/iosMain/kotlin/Database.ios.kt fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> { val dbFilePath = documentDirectory() + "/my_room.db" return Room.databaseBuilder<AppDatabase>( name = dbFilePath, ) } @OptIn(ExperimentalForeignApi::class) private fun documentDirectory(): String { val documentDirectory = NSFileManager.defaultManager.URLForDirectory( directory = NSDocumentDirectory, inDomain = NSUserDomainMask, appropriateForURL = null, create = false, error = null, ) return requireNotNull(documentDirectory?.path) }
Máy tính JVM
Để tạo thực thể cơ sở dữ liệu, hãy cung cấp đường dẫn cơ sở dữ liệu bằng API Java hoặc Kotlin.
// shared/src/jvmMain/kotlin/Database.desktop.kt
fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> {
val dbFile = File(System.getProperty("java.io.tmpdir"), "my_room.db")
return Room.databaseBuilder<AppDatabase>(
name = dbFile.absolutePath,
)
}
Tạo thực thể cho cơ sở dữ liệu
Sau khi lấy được RoomDatabase.Builder từ một trong các hàm khởi tạo dành riêng cho nền tảng, bạn có thể định cấu hình phần còn lại của cơ sở dữ liệu Room trong mã chung cùng với việc tạo thực thể cơ sở dữ liệu thực tế.
// shared/src/commonMain/kotlin/Database.kt fun getRoomDatabase( builder: RoomDatabase.Builder<AppDatabase> ): AppDatabase { return builder .setDriver(BundledSQLiteDriver()) .setQueryCoroutineContext(Dispatchers.IO) .build() }
Chọn một trình điều khiển SQLite
Đoạn mã trước đó gọi hàm trình tạo setDriver để xác định trình điều khiển SQLite mà cơ sở dữ liệu Room nên sử dụng. Các trình điều khiển này khác nhau tuỳ theo nền tảng mục tiêu. Các đoạn mã trước đó sử dụng BundledSQLiteDriver.
Đây là trình điều khiển được đề xuất, bao gồm SQLite được biên dịch từ nguồn, cung cấp phiên bản SQLite nhất quán và mới nhất trên tất cả các nền tảng.
Nếu bạn muốn sử dụng SQLite do hệ điều hành cung cấp, hãy dùng API setDriver trong các nhóm tài nguyên dành riêng cho nền tảng chỉ định trình điều khiển dành riêng cho nền tảng. Hãy xem phần Triển khai trình điều khiển để biết nội dung mô tả về các cách triển khai trình điều khiển hiện có. Bạn có thể sử dụng một trong hai cách sau:
AndroidSQLiteDrivertrongandroidMainNativeSQLiteDrivertrongiosMain
Để sử dụng NativeSQLiteDriver, bạn cần cung cấp tuỳ chọn trình liên kết -lsqlite3 để ứng dụng iOS liên kết linh động với SQLite của hệ thống.
// shared/build.gradle.kts
kotlin {
listOf(
iosX64(),
iosArm64(),
iosSimulatorArm64()
).forEach { iosTarget ->
iosTarget.binaries.framework {
baseName = "TodoApp"
isStatic = true
// Required when using NativeSQLiteDriver
linkerOpts.add("-lsqlite3")
}
}
}
Đặt ngữ cảnh coroutine
Bạn có thể định cấu hình đối tượng RoomDatabase trên Android bằng trình thực thi ứng dụng dùng chung thông qua RoomDatabase.Builder.setQueryExecutor để thực hiện các thao tác với cơ sở dữ liệu.
Vì trình thực thi không tương thích với KMP, nên API setQueryExecutor của Room không có trong commonMain. Thay vào đó, bạn phải định cấu hình đối tượng RoomDatabase bằng CoroutineContext. Bạn có thể đặt đối tượng này bằng RoomDatabase.Builder.setCoroutineContext. Nếu bạn không đặt ngữ cảnh, đối tượng RoomDatabase sẽ mặc định là Dispatchers.IO.
Giảm thiểu và làm rối mã nguồn
Nếu dự án được rút gọn hoặc làm rối mã nguồn, thì bạn phải thêm quy tắc ProGuard sau đây để Room có thể tìm thấy phương thức triển khai được tạo của định nghĩa cơ sở dữ liệu:
-keep class * extends androidx.room3.RoomDatabase { <init>(); }
Di chuyển sang Kotlin Multiplatform
Ban đầu, Room được phát triển dưới dạng thư viện Android và sau đó được di chuyển sang KMP, tập trung vào khả năng tương thích API. Phiên bản KMP của Room có một số điểm khác biệt giữa các nền tảng và so với phiên bản dành riêng cho Android. Những điểm khác biệt này được liệt kê và mô tả như sau.
Di chuyển từ Support SQLite sang SQLite Driver
Mọi trường hợp sử dụng SupportSQLiteDatabase và các API khác trong
androidx.sqlite.db đều cần được tái cấu trúc bằng API Trình điều khiển SQLite,
vì các API trong androidx.sqlite.db chỉ dành cho Android (lưu ý rằng
gói này khác với gói KMP).
Để có khả năng tương thích ngược và miễn là RoomDatabase được định cấu hình bằng SupportSQLiteOpenHelper.Factory (ví dụ: không đặt SQLiteDriver), thì Room sẽ hoạt động ở "chế độ tương thích", trong đó cả API SQLite hỗ trợ và API Trình điều khiển SQLite đều hoạt động như mong đợi. Điều này cho phép di chuyển dần dần để bạn không cần phải chuyển đổi tất cả các trường hợp sử dụng SQLite hỗ trợ sang Trình điều khiển SQLite trong một lần thay đổi.
Sử dụng trình bao bọc SQLite của Room
Cấu phần phần mềm androidx.room3:room3-sqlite-wrapper cung cấp các API để kết nối SQLiteDriver và SupportSQLiteDatabase trong quá trình di chuyển.
Để lấy SupportSQLiteDatabase từ RoomDatabase được định cấu hình bằng SQLiteDriver, hãy sử dụng hàm tiện ích mới RoomDatabase.getSupportWrapper. Trình bao bọc tương thích này giúp duy trì
các cách sử dụng hiện có của SupportSQLiteDatabase (thường lấy từ
RoomDatabase.openHelper.writableDatabase) trong khi áp dụng SQLiteDriver,
đặc biệt là đối với các cơ sở mã có mức sử dụng API SupportSQLite rộng rãi muốn
sử dụng BundledSQLiteDriver.
Chuyển đổi các lớp con di chuyển
Các lớp con di chuyển cần được di chuyển sang các lớp con tương ứng của trình điều khiển SQLite:
Kotlin Multiplatform
Lớp con di chuyển
object Migration_1_2 : Migration(1, 2) { override suspend fun migrate(connection: SQLiteConnection) { // ... } }
Lớp con của thông số kỹ thuật di chuyển tự động
class AutoMigrationSpec_1_2 : AutoMigrationSpec { override suspend fun onPostMigrate(connection: SQLiteConnection) { // ... } }
Chỉ dành cho Android
Lớp con di chuyển
object Migration_1_2 : Migration(1, 2) {
override fun migrate(db: SupportSQLiteDatabase) {
// …
}
}
Lớp con của thông số kỹ thuật di chuyển tự động
class AutoMigrationSpec_1_2 : AutoMigrationSpec {
override fun onPostMigrate(db: SupportSQLiteDatabase) {
// …
}
}
Chuyển đổi lệnh gọi lại cơ sở dữ liệu
Bạn cần di chuyển lệnh gọi lại cơ sở dữ liệu sang các lệnh gọi lại tương ứng của trình điều khiển SQLite:
Kotlin Multiplatform
object MyRoomCallback : RoomDatabase.Callback() { override suspend fun onCreate(connection: SQLiteConnection) { // ... } override suspend fun onDestructiveMigration(connection: SQLiteConnection) { // ... } override suspend fun onOpen(connection: SQLiteConnection) { // ... } }
Chỉ dành cho Android
object MyRoomCallback : RoomDatabase.Callback() {
override fun onCreate(db: SupportSQLiteDatabase) {
// …
}
override fun onDestructiveMigration(db: SupportSQLiteDatabase) {
// …
}
override fun onOpen(db: SupportSQLiteDatabase) {
// …
}
}
Chuyển đổi các hàm DAO @RawQuery
Các hàm được chú thích bằng @RawQuery được biên dịch cho các nền tảng không phải Android sẽ cần khai báo một tham số thuộc loại RoomRawQuery thay vì SupportSQLiteQuery.
Kotlin Multiplatform
Xác định truy vấn thô
@Dao interface TodoDao { @RawQuery suspend fun getTodos(query: RoomRawQuery): List<TodoEntity> }
Sau đó, bạn có thể dùng RoomRawQuery để tạo truy vấn trong thời gian chạy:
suspend fun AppDatabase.getTodosWithLowercaseTitle(title: String): List<TodoEntity> { val query = RoomRawQuery( sql = "SELECT * FROM TodoEntity WHERE title = ?", onBindStatement = { it.bindText(1, title.lowercase()) } ) return getDao().getTodos(query) }
Chỉ dành cho Android
Xác định truy vấn thô
@Dao
interface TodoDao {
@RawQuery
suspend fun getTodos(query: SupportSQLiteQuery): List<TodoEntity>
}
Sau đó, bạn có thể dùng SimpleSQLiteQuery để tạo truy vấn trong thời gian chạy:
suspend fun AndroidOnlyDao.getTodosWithLowercaseTitle(title: String): List<TodoEntity> {
val query = SimpleSQLiteQuery(
query = "SELECT * FROM TodoEntity WHERE title = ?",
bindArgs = arrayOf(title.lowercase())
)
return getTodos(query)
}
Chuyển đổi các hàm DAO chặn
Room hưởng lợi từ thư viện kotlinx.coroutines không đồng bộ, giàu tính năng mà Kotlin cung cấp cho nhiều nền tảng. Để có chức năng tối ưu, các hàm suspend được thực thi cho DAO được biên dịch trong dự án KMP, ngoại trừ DAO được triển khai trong androidMain để duy trì khả năng tương thích ngược với toàn bộ mã nguồn hiện có. Khi sử dụng Room cho KMP, tất cả hàm DAO được biên dịch cho các nền tảng không phải Nền tảng Android đều phải là hàm suspend.
Kotlin Multiplatform
Tạm ngưng truy vấn
@Query("SELECT * FROM Todo") suspend fun getAllTodos(): List<Todo>
Tạm ngưng giao dịch
@Transaction suspend fun transaction() { // ... }
Chỉ dành cho Android
Truy vấn chặn
@Query("SELECT * FROM Todo")
fun getAllTodos(): List<Todo>
Chặn giao dịch
@Transaction
fun blockingTransaction() { … }
Chuyển đổi các loại phản ứng thành Flow
Không phải hàm DAO nào cũng cần phải là hàm tạm ngưng. Không nên chuyển đổi các hàm DAO trả về loại phản ứng như LiveData hoặc Flowable của RxJava thành hàm tạm ngưng. Tuy nhiên, một số loại (chẳng hạn như LiveData) không tương thích với KMP. Các hàm DAO có kiểu dữ liệu trả về phản ứng phải được di chuyển sang
luồng coroutine.
Kotlin Multiplatform
Loại phản ứng Flows
@Query("SELECT * FROM Todo") fun getTodosFlow(): Flow<List<Todo>>
Chỉ dành cho Android
Các loại phản ứng như LiveData hoặc Flowable của RxJava
@Query("SELECT * FROM Todo")
fun getTodosLiveData(): LiveData<List<Todo>>
Chuyển đổi API giao dịch
API giao dịch cơ sở dữ liệu cho Room KMP có thể phân biệt giữa giao dịch ghi (useWriterConnection) và giao dịch đọc (useReaderConnection).
Kotlin Multiplatform
val database: RoomDatabase = getRoomDatabase(builder) database.useWriterConnection { transactor -> transactor.immediateTransaction { // perform database operations in transaction. } }
Chỉ dành cho Android
val database: RoomDatabase = …
database.withTransaction {
// perform database operations in transaction
}
Ghi dữ liệu giao dịch
Sử dụng giao dịch ghi để đảm bảo rằng nhiều truy vấn ghi dữ liệu một cách nguyên tử, nhờ đó, trình đọc có thể truy cập dữ liệu một cách nhất quán. Bạn có thể thực hiện việc này bằng cách sử dụng useWriterConnection với bất kỳ loại giao dịch nào trong số ba loại giao dịch sau:
immediateTransaction: Ở chế độ Ghi nhật ký trước khi ghi (WAL) (mặc định), loại giao dịch này sẽ có khoá khi bắt đầu, nhưng trình đọc có thể tiếp tục đọc. Đây là lựa chọn ưu tiên cho hầu hết các trường hợp.deferredTransaction: Giao dịch sẽ không nhận được khoá cho đến khi có câu lệnh ghi đầu tiên. Hãy sử dụng loại giao dịch này làm phương án tối ưu hoá khi bạn không chắc liệu có cần thao tác ghi trong giao dịch hay không. Ví dụ: nếu bạn bắt đầu một giao dịch để xoá các bài hát khỏi một danh sách phát chỉ có tên của danh sách phát và danh sách phát đó không tồn tại, thì bạn không cần thực hiện thao tác ghi (xoá).exclusiveTransaction: Chế độ này hoạt động giống hệt vớiimmediateTransactionở chế độ WAL. Trong các chế độ ghi nhật ký khác, chế độ này ngăn các kết nối cơ sở dữ liệu khác đọc cơ sở dữ liệu trong khi giao dịch đang diễn ra.
Đọc giao dịch
Sử dụng giao dịch đọc để đọc nhất quán từ cơ sở dữ liệu nhiều lần. Ví dụ: khi bạn có hai hoặc nhiều truy vấn riêng biệt và không sử dụng mệnh đề JOIN. Chỉ cho phép giao dịch bị trì hoãn trong các kết nối với đầu đọc. Nếu bạn cố gắng bắt đầu một giao dịch ngay lập tức hoặc độc quyền trong một kết nối trình đọc, thì hệ thống sẽ gửi một ngoại lệ vì đây được coi là các thao tác "ghi".
val database: RoomDatabase = getRoomDatabase(builder) database.useReaderConnection { transactor -> transactor.deferredTransaction { // perform database operations in transaction. } }
Không có trong Kotlin Multiplatform
Một số API có sẵn cho Android không có trong Kotlin Multiplatform.
Lệnh gọi lại truy vấn
Các API sau đây để định cấu hình lệnh gọi lại truy vấn không có sẵn trong mã chung và do đó không có sẵn trong các nền tảng khác ngoài Android.
RoomDatabase.Builder.setQueryCallbackRoomDatabase.QueryCallback
Cơ sở dữ liệu tự động đóng
API để bật tính năng tự động đóng sau khi hết thời gian chờ,
RoomDatabase.Builder.setAutoCloseTimeout, chỉ có trên Android.
Cơ sở dữ liệu đóng gói sẵn
Các API sau đây để tạo RoomDatabase bằng cơ sở dữ liệu hiện có (cơ sở dữ liệu đóng gói sẵn) không có sẵn trong mã chung và do đó không có sẵn trong các nền tảng khác ngoài Android:
RoomDatabase.Builder.createFromAssetRoomDatabase.Builder.createFromFileRoomDatabase.Builder.createFromInputStreamRoomDatabase.PrepackagedDatabaseCallback
Vô hiệu hoá nhiều phiên bản
API để bật tính năng vô hiệu hoá nhiều phiên bản,
RoomDatabase.Builder.enableMultiInstanceInvalidation, chỉ có trên
Android và không có trên các nền tảng phổ biến hoặc nền tảng khác.
Đề xuất cho bạn
- Lưu ý: văn bản có đường liên kết sẽ hiện khi JavaScript tắt
- Lớp học lập trình về cách di chuyển các ứng dụng hiện có sang Room KMP
- Lớp học lập trình về cách bắt đầu sử dụng KMP
- Lưu dữ liệu trong cơ sở dữ liệu cục bộ bằng Room