توفّر مكتبة Room لاستدامة البيانات طبقة تجريد فوق SQLite للسماح بالوصول إلى قاعدة البيانات بشكل أكثر فعالية مع الاستفادة من الإمكانات الكاملة لـ SQLite. تركّز هذه الصفحة على استخدام Room في مشاريع Kotlin Multiplatform (KMP). لمزيد من المعلومات حول استخدام Room، يُرجى الاطّلاع على حفظ البيانات في قاعدة بيانات محلية باستخدام Room أو النماذج الرسمية.
إعداد التبعيات
لإعداد Room في مشروع KMP، أضِف الاعتماديات الخاصة بالعناصر في ملف build.gradle.kts لوحدة KMP.
حدِّد التبعيات في ملف 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" }
أضِف مكوّن Room Gradle الإضافي لضبط مخططات Room ومكوّن KSP الإضافي.
plugins {
alias(libs.plugins.ksp)
alias(libs.plugins.androidx.room3)
}
أضِف اعتمادية وقت تشغيل Room ومكتبة SQLite المجمّعة:
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)
}
أضِف اعتماديات KSP إلى مجموعة root dependencies. يجب إضافة جميع الأهداف
التي يستخدمها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على KSP مع
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
}
حدِّد دليل مخطط Room. لمزيد من المعلومات، يُرجى الاطّلاع على ضبط موقع المخطط باستخدام مكوّن Room Gradle الإضافي.
room {
schemaDirectory("$projectDir/schemas")
}
تحديد فئات قاعدة البيانات
عليك إنشاء فئة قاعدة بيانات تتضمّن التعليق التوضيحي @Database مع كائنات الوصول إلى البيانات (DAO) والكيانات داخل مجموعة رموز المصدر الشائعة لوحدة KMP المشترَكة. سيسمح وضع هذه الفئات في مصادر مشتركة بمشاركتها عبر جميع الأنظمة الأساسية المستهدفة.
// 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 }
عند تعريف عنصر expect باستخدام واجهة RoomDatabaseConstructor، ينشئ برنامج تجميع Room عمليات تنفيذ actual. قد يُصدر "استوديو Android" التحذير التالي، والذي يمكنك
إيقافه باستخدام @Suppress("KotlinNoActualForExpect"):
Expected object 'AppDatabaseConstructor' has no actual declaration in module`
بعد ذلك، حدِّد واجهة DAO جديدة أو انقل واجهة حالية إلى
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>> }
حدِّد الكيانات أو انقلها إلى commonMain:
// shared/src/commonMain/kotlin/TodoEntity.kt @Entity data class TodoEntity( @PrimaryKey(autoGenerate = true) val id: Long = 0, val title: String, val content: String )
إنشاء أدوات إنشاء قواعد بيانات خاصة بالمنصة
عليك تحديد أداة إنشاء قاعدة بيانات لإنشاء مثيل من Room على كل نظام أساسي. هذا هو الجزء الوحيد من واجهة برمجة التطبيقات الذي يجب تحديده في مجموعات رموز المصدر الخاصة بالنظام الأساسي، وذلك بسبب الاختلافات في واجهات برمجة التطبيقات لنظام الملفات.
Android
على Android، يمكنك عادةً الحصول على الموقع الجغرافي لقاعدة البيانات باستخدام واجهة برمجة التطبيقات Context.getDatabasePath. لإنشاء مثيل قاعدة البيانات، حدِّد
Context ومسار قاعدة البيانات.
// 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
لإنشاء مثيل قاعدة البيانات على iOS، أدخِل مسار قاعدة البيانات باستخدام
NSFileManager، والذي يقع عادةً في 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) }
أجهزة الكمبيوتر المكتبية التي تعمل بنظام JVM
لإنشاء مثيل قاعدة البيانات، قدِّم مسار قاعدة بيانات باستخدام واجهات برمجة تطبيقات Java أو 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,
)
}
إنشاء مثيل لقاعدة البيانات
بعد الحصول على RoomDatabase.Builder من إحدى الدوال الإنشائية الخاصة بالنظام الأساسي، يمكنك ضبط بقية قاعدة بيانات Room في الرمز البرمجي المشترك مع إنشاء مثيل قاعدة البيانات الفعلي.
// shared/src/commonMain/kotlin/Database.kt fun getRoomDatabase( builder: RoomDatabase.Builder<AppDatabase> ): AppDatabase { return builder .setDriver(BundledSQLiteDriver()) .setQueryCoroutineContext(Dispatchers.IO) .build() }
اختيار برنامج تشغيل SQLite
يستدعي مقتطف الرمز السابق دالة الإنشاء setDriver لتحديد برنامج تشغيل SQLite الذي يجب أن تستخدمه قاعدة بيانات Room. تختلف برامج التشغيل هذه بناءً على
النظام الأساسي المستهدف. تستخدم مقتطفات الرموز السابقة السمة BundledSQLiteDriver.
وهو برنامج التشغيل المقترَح الذي يتضمّن SQLite مجمَّعًا من المصدر، ما يوفّر الإصدار الأكثر اتساقًا وحداثة من SQLite على جميع المنصات.
إذا أردت استخدام SQLite الذي يوفّره نظام التشغيل، استخدِم واجهة برمجة التطبيقات setDriver في مجموعات رموز المصدر الخاصة بالنظام الأساسي والتي تحدّد برنامج تشغيل خاصًا بالنظام الأساسي. يمكنك الاطّلاع على عمليات تنفيذ برامج التشغيل للحصول على أوصاف لعمليات تنفيذ برامج التشغيل المتاحة. يمكنك استخدام أيّ مما يلي:
AndroidSQLiteDriverفيandroidMainNativeSQLiteDriverفيiosMain
لاستخدام NativeSQLiteDriver، عليك توفير خيار الربط -lsqlite3 لكي
يتم ربط تطبيق iOS ديناميكيًا بنظام SQLite.
// 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")
}
}
}
ضبط سياق دالة coroutine
يمكن اختياريًا ضبط كائن RoomDatabase على Android باستخدام منفّذي التطبيقات المشتركة باستخدام RoomDatabase.Builder.setQueryExecutor لتنفيذ عمليات قاعدة البيانات.
بما أنّ المنفّذين غير متوافقين مع KMP، فإنّ واجهة برمجة التطبيقات setQueryExecutor في Room غير متاحة في commonMain. بدلاً من ذلك، يجب ضبط عنصر RoomDatabase باستخدام CoroutineContext، والذي يمكنك ضبطه باستخدام RoomDatabase.Builder.setCoroutineContext. إذا لم تضبط سياقًا، يتم ضبط عنصر RoomDatabase تلقائيًا على Dispatchers.IO.
إزالة البيانات غير الضرورية والتشويش
إذا كان المشروع مُصغّرًا أو مخفيًا، يجب تضمين قاعدة ProGuard التالية حتى تتمكّن Room من العثور على التنفيذ الذي تم إنشاؤه لتعريف قاعدة البيانات:
-keep class * extends androidx.room3.RoomDatabase { <init>(); }
نقل البيانات إلى Kotlin Multiplatform
تم تطوير Room في الأصل كمكتبة Android، ثم تم نقلها لاحقًا إلى KMP مع التركيز على توافق واجهة برمجة التطبيقات. يختلف إصدار KMP من Room إلى حدّ ما بين الأنظمة الأساسية ومن الإصدار الخاص بنظام Android. يتم سرد هذه الاختلافات ووصفها على النحو التالي.
نقل البيانات من Support SQLite إلى SQLite Driver
يجب إعادة صياغة أي استخدامات لـ SupportSQLiteDatabase وواجهات برمجة التطبيقات الأخرى في
androidx.sqlite.db باستخدام واجهات برمجة تطبيقات SQLite Driver،
لأنّ واجهات برمجة التطبيقات في androidx.sqlite.db مخصّصة لنظام التشغيل Android فقط (يُرجى ملاحظة
الحزمة المختلفة عن حزمة KMP).
للتوافق مع الأنظمة القديمة، وطالما تم إعداد RoomDatabase باستخدام SupportSQLiteOpenHelper.Factory (على سبيل المثال، لم يتم ضبط SQLiteDriver)، تعمل Room في "وضع التوافق" حيث تعمل كل من واجهات برمجة التطبيقات Support SQLite وSQLite Driver كما هو متوقع. يتيح ذلك عمليات نقل البيانات المتزايدة، وبالتالي لن تحتاج إلى تحويل جميع استخدامات Support SQLite إلى SQLite Driver في تغيير واحد.
استخدام برنامج تضمين SQLite في Room
توفّر عناصر androidx.room3:room3-sqlite-wrapper واجهات برمجة تطبيقات للربط
بين SQLiteDriver وSupportSQLiteDatabase أثناء عملية النقل.
للحصول على SupportSQLiteDatabase من RoomDatabase تم إعداده باستخدام
SQLiteDriver، استخدِم دالة الإضافة الجديدة
RoomDatabase.getSupportWrapper. يساعد برنامج تضمين التوافق هذا في الحفاظ على
الاستخدامات الحالية لـ SupportSQLiteDatabase، والتي غالبًا ما تحصل عليها من
RoomDatabase.openHelper.writableDatabase، أثناء استخدام SQLiteDriver،
خاصةً لقواعد الرموز البرمجية التي تستخدم واجهة برمجة التطبيقات SupportSQLite على نطاق واسع وتريد
استخدام BundledSQLiteDriver.
تحويل الفئات الفرعية لنقل البيانات
يجب نقل الفئات الفرعية لعمليات نقل البيانات إلى الفئات المقابلة في برنامج تشغيل SQLite:
Kotlin Multiplatform
الفئات الفرعية لنقل البيانات
object Migration_1_2 : Migration(1, 2) { override suspend fun migrate(connection: SQLiteConnection) { // ... } }
الفئات الفرعية لمواصفات النقل التلقائي
class AutoMigrationSpec_1_2 : AutoMigrationSpec { override suspend fun onPostMigrate(connection: SQLiteConnection) { // ... } }
على أجهزة Android فقط
الفئات الفرعية لنقل البيانات
object Migration_1_2 : Migration(1, 2) {
override fun migrate(db: SupportSQLiteDatabase) {
// …
}
}
الفئات الفرعية لمواصفات النقل التلقائي
class AutoMigrationSpec_1_2 : AutoMigrationSpec {
override fun onPostMigrate(db: SupportSQLiteDatabase) {
// …
}
}
تحويل استدعاء قاعدة البيانات
يجب نقل عمليات معاودة الاتصال بقاعدة البيانات إلى نظيراتها في برنامج تشغيل 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) { // ... } }
على أجهزة Android فقط
object MyRoomCallback : RoomDatabase.Callback() {
override fun onCreate(db: SupportSQLiteDatabase) {
// …
}
override fun onDestructiveMigration(db: SupportSQLiteDatabase) {
// …
}
override fun onOpen(db: SupportSQLiteDatabase) {
// …
}
}
تحويل دوال DAO عددها @RawQuery
بالنسبة إلى الدوال التي تم تجميعها للأنظمة الأساسية غير نظام Android الأساسي والتي تم التعليق عليها باستخدام @RawQuery، يجب أن تعلن عن مَعلمة من النوع RoomRawQuery بدلاً من SupportSQLiteQuery.
Kotlin Multiplatform
تحديد طلب البحث الأولي
@Dao interface TodoDao { @RawQuery suspend fun getTodos(query: RoomRawQuery): List<TodoEntity> }
يمكن بعد ذلك استخدام RoomRawQuery لإنشاء طلب بحث في وقت التشغيل:
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) }
على أجهزة Android فقط
تحديد طلب البحث الأولي
@Dao
interface TodoDao {
@RawQuery
suspend fun getTodos(query: SupportSQLiteQuery): List<TodoEntity>
}
يمكن بعد ذلك استخدام SimpleSQLiteQuery لإنشاء طلب بحث في وقت التشغيل:
suspend fun AndroidOnlyDao.getTodosWithLowercaseTitle(title: String): List<TodoEntity> {
val query = SimpleSQLiteQuery(
query = "SELECT * FROM TodoEntity WHERE title = ?",
bindArgs = arrayOf(title.lowercase())
)
return getTodos(query)
}
تحويل دوال DAO التي تحظر الوصول إلى قاعدة البيانات
تستفيد Room من مكتبة kotlinx.coroutines غير المتزامنة والغنية بالميزات التي توفّرها Kotlin لمنصات متعددة. لتحقيق الأداء الأمثل، يتم فرض دوال suspend على كائنات الوصول إلى البيانات (DAO) التي يتم تجميعها في مشروع KMP، باستثناء كائنات الوصول إلى البيانات التي يتم تنفيذها في androidMain للحفاظ على التوافق مع الأنظمة القديمة لقاعدة الرموز البرمجية الحالية. عند استخدام Room في KMP، يجب أن تكون جميع دوال DAO التي تم تجميعها لأنظمة أساسية غير نظام Android الأساسي دوال suspend.
Kotlin Multiplatform
طلبات البحث التي يتم تعليقها
@Query("SELECT * FROM Todo") suspend fun getAllTodos(): List<Todo>
تعليق المعاملات
@Transaction suspend fun transaction() { // ... }
على أجهزة Android فقط
طلبات الحظر
@Query("SELECT * FROM Todo")
fun getAllTodos(): List<Todo>
حظر المعاملات
@Transaction
fun blockingTransaction() { … }
تحويل الأنواع التفاعلية إلى Flow
ليس من الضروري أن تكون جميع دوال DAO دوال تعليق. يجب عدم تحويل دوال DAO التي تعرض أنواعًا تفاعلية مثل LiveData أو Flowable في RxJava إلى دوال تعليق. ومع ذلك، فإنّ بعض الأنواع، مثل LiveData، غير متوافقة مع KMP. يجب نقل دوال DAO التي تتضمّن أنواع القيم التي تم إرجاعها تفاعلية إلى تدفقات الكوروتين.
Kotlin Multiplatform
أنواع التفاعلات Flows
@Query("SELECT * FROM Todo") fun getTodosFlow(): Flow<List<Todo>>
على أجهزة Android فقط
الأنواع التفاعلية مثل LiveData أو Flowable من RxJava
@Query("SELECT * FROM Todo")
fun getTodosLiveData(): LiveData<List<Todo>>
تحويل واجهات برمجة التطبيقات الخاصة بالمعاملات
يمكن لواجهات برمجة التطبيقات الخاصة بمعاملات قواعد البيانات في Room KMP التمييز بين معاملات الكتابة
(useWriterConnection) والقراءة (useReaderConnection).
Kotlin Multiplatform
val database: RoomDatabase = getRoomDatabase(builder) database.useWriterConnection { transactor -> transactor.immediateTransaction { // perform database operations in transaction. } }
على أجهزة Android فقط
val database: RoomDatabase = …
database.withTransaction {
// perform database operations in transaction
}
كتابة المعاملات
استخدِم معاملات الكتابة للتأكّد من أنّ طلبات البحث المتعدّدة تكتب البيانات بشكل ذري،
ليتمكّن القرّاء من الوصول إلى البيانات بشكل متّسق. يمكنك إجراء ذلك باستخدام
useWriterConnection مع أي من أنواع المعاملات الثلاثة:
immediateTransaction: في وضع تسجيل الكتابة المسبقة (WAL) (الوضع التلقائي)، يحصل هذا النوع من المعاملات على قفل عند بدئه، ولكن يمكن للقراء مواصلة القراءة. هذا هو الخيار المفضّل في معظم الحالات.
deferredTransaction: لن تحصل المعاملة على قفل حتى يتم تنفيذ أول عبارة كتابة. استخدِم هذا النوع من المعاملات كعملية تحسين عندما لا تكون متأكدًا مما إذا كانت عملية الكتابة ستكون مطلوبة ضمن المعاملة. على سبيل المثال، إذا بدأت معاملة لحذف أغانٍ من قائمة تشغيل معيّنة باسم قائمة التشغيل فقط ولم تكن قائمة التشغيل موجودة، لن تكون هناك حاجة إلى إجراء عملية كتابة (حذف).exclusiveTransaction: يعمل هذا الوضع بشكل مماثل لـimmediateTransactionفي وضع WAL. في أوضاع التسجيل الأخرى، يمنع هذا القفل اتصالات قاعدة البيانات الأخرى من قراءة قاعدة البيانات أثناء إجراء المعاملة.
قراءة المعاملات
استخدِم معاملات القراءة للقراءة من قاعدة البيانات عدة مرات بشكل متّسق. على سبيل المثال، عندما يكون لديك طلبان منفصلان أو أكثر ولا تستخدم عبارة JOIN. يُسمح فقط بالمعاملات المؤجَّلة في عمليات ربط القارئ. ستؤدي محاولة بدء معاملة فورية أو حصرية في اتصال قارئ إلى ظهور استثناء، لأنّ هذه المعاملات تُعتبر عمليات "كتابة".
val database: RoomDatabase = getRoomDatabase(builder) database.useReaderConnection { transactor -> transactor.deferredTransaction { // perform database operations in transaction. } }
غير متاحة في Kotlin Multiplatform
بعض واجهات برمجة التطبيقات التي كانت متاحة لنظام التشغيل Android غير متاحة في Kotlin Multiplatform.
معاودة الاتصال بطلب البحث
لا تتوفّر واجهات برمجة التطبيقات التالية لضبط عمليات الاستدعاء لطلبات البحث في common، وبالتالي لا تتوفّر في الأنظمة الأساسية الأخرى غير Android.
RoomDatabase.Builder.setQueryCallbackRoomDatabase.QueryCallback
قاعدة بيانات تُغلق تلقائيًا
لا تتوفّر واجهة برمجة التطبيقات لتفعيل الإغلاق التلقائي بعد انتهاء المهلة،
RoomDatabase.Builder.setAutoCloseTimeout، إلا على أجهزة Android.
قاعدة بيانات مُعدّة مسبقًا
لا تتوفّر واجهات برمجة التطبيقات التالية لإنشاء RoomDatabase باستخدام قاعدة بيانات حالية (قاعدة بيانات مُعدّة مسبقًا) بشكل شائع، وبالتالي لا تتوفّر في الأنظمة الأساسية غير Android:
RoomDatabase.Builder.createFromAssetRoomDatabase.Builder.createFromFileRoomDatabase.Builder.createFromInputStreamRoomDatabase.PrepackagedDatabaseCallback
إبطال النُسخ المتعددة
لا تتوفّر واجهة برمجة التطبيقات لتفعيل الإبطال في وضع فتح نسختين من التطبيق،
RoomDatabase.Builder.enableMultiInstanceInvalidation، إلا على
Android، وهي غير متاحة على الأنظمة الأساسية الشائعة أو الأخرى.
التطبيقات المقترَحة لك
- ملاحظة: يتم عرض نص الرابط عندما يكون JavaScript غير مفعَّل
- الدرس التطبيقي حول الترميز: نقل التطبيقات الحالية إلى Room KMP
- بدء استخدام الدرس التطبيقي حول الترميز في KMP
- حفظ البيانات في قاعدة بيانات محلية باستخدام Room