نقل البيانات من SQLite إلى غرفة

توفّر مكتبة Room لاستدامة البيانات عددًا من المزايا مقارنةً باستخدام واجهات برمجة التطبيقات SQLite مباشرةً، وهي:

• التحقّق من صحة طلبات البحث بلغة SQL في وقت الترجمة البرمجية
• التعليقات التوضيحية التي تسهّل الاستخدام وتقلّل من النصوص النموذجية المتكررة والمعرَّضة للأخطاء
• مسارات مبسطة لنقل قواعد البيانات

إذا كان تطبيقك يتضمّن عملية تنفيذ SQLite غير Room، يُرجى قراءة هذه الصفحة للتعرّف على كيفية نقل البيانات إلى Room. إذا كان Room هو أول عملية تنفيذ لـ SQLite في تطبيقك، راجِع حفظ البيانات في قاعدة بيانات محلية باستخدام Room لمعرفة الاستخدام الأساسي.

خطوات نقل البيانات

اتّبِع الخطوات التالية لنقل عملية تنفيذ SQLite إلى Room. إذا كان تطبيق SQLite يستخدم قاعدة بيانات كبيرة أو استعلامات معقّدة، قد يكون من الأفضل نقل البيانات إلى Room تدريجيًا. لمزيد من المعلومات حول استراتيجية النقل التدريجي، اطّلِع على النقل التدريجي.

تعديل التبعيات

لاستخدام Room في تطبيقك، يجب تضمين التبعيات المناسبة في ملف build.gradle الخاص بالتطبيق. لمزيد من المعلومات حول الاعتماديات في Room، يُرجى الاطّلاع على الإعداد.

تعديل فئات النماذج إلى عناصر البيانات

يستخدم Room كيانات البيانات لتمثيل الجداول في قاعدة البيانات. يمثّل كل فئة من فئات العناصر جدولاً ويتضمّن خصائص تمثّل الأعمدة في هذا الجدول. اتّبِع الخطوات التالية لتعديل فئات النماذج الحالية لتصبح عناصر Room:

1. أضِف التعليق التوضيحي @Entity إلى تعريف الفئة للإشارة إلى أنّها كيان Room. يمكنك اختياريًا استخدام السمة tableName للإشارة إلى أنّ الجدول الناتج يجب أن يكون له اسم مختلف عن اسم الفئة.
2. أضِف تعليقًا توضيحيًا إلى سمة المفتاح الأساسي باستخدام @PrimaryKey.
3. إذا كان أي من الأعمدة في الجدول الناتج يجب أن يكون له اسم مختلف عن اسم السمة المقابلة، أضِف تعليقًا توضيحيًا إلى السمة باستخدام @ColumnInfo واضبط السمة name على اسم العمود الصحيح.
4. إذا كانت الفئة تتضمّن خصائص لا تريد الاحتفاظ بها في قاعدة البيانات، أضِف التعليق التوضيحي @Ignore إلى هذه الخصائص للإشارة إلى أنّ Room يجب ألا ينشئ أعمدة لها في الجدول المقابل.
5. إذا كان للصف أكثر من دالة إنشائية واحدة، حدِّد الدالة الإنشائية التي يجب أن يستخدمها Room عن طريق إضافة التعليق التوضيحي @Ignore إلى جميع الدوال الإنشائية الأخرى.

@Entity(tableName = "users")
data class User(
    @PrimaryKey @ColumnInfo(name = "userid") val id: String,
    @ColumnInfo(name = "username") val userName: String?,
    @ColumnInfo(name = "last_update") val date: Date?,
)
SqliteRoomMigrationSnippets.kt

إنشاء منظمات مستقلة لامركزية

يستخدم Room عناصر الوصول إلى البيانات (DAO) لتحديد الدوال التي تصل إلى قاعدة البيانات. اتّبِع الإرشادات الواردة في الوصول إلى البيانات باستخدام عناصر DAO في Room لاستبدال دوال طلب البحث الحالية بعناصر DAO.

إنشاء فئة قاعدة بيانات

تستخدِم عمليات تنفيذ Room فئة قاعدة بيانات لإدارة مثيل قاعدة البيانات. يجب أن توسّع فئة قاعدة البيانات RoomDatabase وأن تشير إلى جميع الكيانات وعناصر الوصول إلى البيانات التي حدّدتها.

@Database(entities = [User::class], version = 2)
@ColumnTypeConverters(DateConverter::class)
abstract class UsersDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}
SqliteRoomMigrationSnippets.kt

تحديد مسار نقل البيانات

بما أنّ رقم إصدار قاعدة البيانات سيتغيّر، عليك تحديد عنصر Migration للاحتفاظ ببيانات قاعدة البيانات الحالية. إذا لم يتغيّر مخطط قاعدة البيانات، يمكن أن تكون عملية النقل هذه فارغة.

val MIGRATION_1_2 = object : Migration(1, 2) {
    override suspend fun migrate(connection: SQLiteConnection) {
        // Empty implementation, because the schema isn't changing.
    }
}
SqliteRoomMigrationSnippets.kt

لمزيد من المعلومات حول مسارات نقل البيانات في قاعدة البيانات في Room، راجِع نقل بيانات قاعدة البيانات.

تعديل إنشاء قاعدة البيانات

بعد تحديد فئة قاعدة البيانات ومسار النقل، يمكنك استخدام Room.databaseBuilder لإنشاء مثيل لقاعدة البيانات مع تطبيق مسار النقل:

val db =
    Room.databaseBuilder<UsersDatabase>(applicationContext, "database-name")
        .addMigrations(MIGRATION_1_2)
        .build()
SqliteRoomMigrationSnippets.kt

اختبار عملية التنفيذ

احرص على اختبار عملية تنفيذ Room الجديدة باتّباع الخطوات التالية:

• اتّبِع الإرشادات الواردة في عمليات الترحيل التجريبية لاختبار عملية ترحيل قاعدة البيانات.
• اتّبِع الإرشادات الواردة في اختبار قاعدة البيانات لاختبار دوال DAO.

نقل البيانات بشكل تدريجي

إذا كان تطبيقك يستخدم قاعدة بيانات كبيرة ومعقّدة، قد لا يكون من الممكن نقل تطبيقك إلى Room دفعة واحدة. بدلاً من ذلك، يمكنك اختياريًا تنفيذ عناصر البيانات وقاعدة بيانات Room كخطوة أولى، ثم نقل دوال طلب البحث إلى عناصر الوصول إلى البيانات (DAO) لاحقًا.

لتنفيذ عملية نقل تدريجية، احصل على برنامج تضمين متوافق مع SupportSQLiteDatabase باستخدام دالة الإضافة roomDatabase.getSupportWrapper من العنصر androidx.room3:room3-sqlite-wrapper. يتيح لك هذا البرنامج المغلّف تنفيذ طلبات بحث مباشرة بلغة SQL على قاعدة البيانات التي تديرها Room باستخدام واجهات برمجة تطبيقات Android SQLite:

// Get SupportSQLiteDatabase wrapper
val legacyDb = roomDatabase.getSupportWrapper()
legacyDb.execSQL("INSERT INTO users ...")
SqliteRoomMigrationSnippets.kt