تعبئة قاعدة بيانات الغرفة بشكل مسبق

إذا أردت أن يبدأ تطبيقك بقاعدة بيانات محملة مسبقًا بمجموعة معيّنة من البيانات، يمكنك ملء قاعدة البيانات مسبقًا. في Room، يمكنك استخدام واجهات برمجة التطبيقات لملء قاعدة بيانات مسبقًا عند التهيئة بمحتويات من ملف قاعدة بيانات مُعدّ مسبقًا في نظام ملفات الجهاز.

الملء المسبق من مادة عرض التطبيق

لملء قاعدة بيانات Room مسبقًا من ملف قاعدة بيانات مُعدّ مسبقًا موجود في أي مكان في دليل assets/ الخاص بتطبيقك، استخدِم الدالة createFromAsset من عنصر RoomDatabase.Builder قبل استخدام build:

Room.databaseBuilder<AppDatabase>(appContext, "sample.db")
    .createFromAsset("database/myapp.db")
    .build()
PrepopulateSnippets.kt

تقبل الدالة createFromAsset وسيطة سلسلة تحتوي على مسار نسبي من دليل assets/ إلى ملف قاعدة البيانات المُعدّ مسبقًا.

الملء المسبق من نظام الملفات

لملء قاعدة بيانات Room مسبقًا من ملف قاعدة بيانات مُعدّ مسبقًا موجود في أي مكان في نظام ملفات الجهاز باستثناء دليل assets/ الخاص بتطبيقك، استخدِم الدالة createFromFile من عنصر RoomDatabase.Builder قبل استخدام build:

Room.databaseBuilder<AppDatabase>(appContext, "sample.db")
    .createFromFile(File("mypath"))
    .build()
PrepopulateSnippets.kt

تقبل الدالة createFromFile وسيطة File لملف قاعدة البيانات المُعدّ مسبقًا. تنشئ Room نسخة من الملف المحدّد بدلاً من فتحه مباشرةً، لذا تأكّد من أنّ تطبيقك لديه أذونات قراءة الملف.

التعامل مع عمليات نقل البيانات التي تتضمّن قواعد بيانات مُعدّة مسبقًا

يمكن أن تغيّر ملفات قاعدة البيانات المُعدّة مسبقًا أيضًا طريقة تعامل قاعدة بيانات Room مع عمليات نقل البيانات الاحتياطية. في العادة، عند تفعيل عمليات نقل البيانات المدمّرة ويجب أن تنفّذ Room عملية نقل بيانات بدون مسار نقل بيانات، ستزيل Room جميع الجداول في قاعدة البيانات وتنشئ قاعدة بيانات فارغة بالمخطط المحدّد للإصدار المستهدَف. ومع ذلك، إذا تضمّنت ملف قاعدة بيانات مُعدّ مسبقًا بالرقم نفسه للإصدار المستهدَف، ستملأ Room قاعدة البيانات التي تم إنشاؤها حديثًا بمحتويات ملف قاعدة البيانات المُعدّ مسبقًا بعد تنفيذ عملية نقل البيانات المدمّرة.

لمزيد من المعلومات عن عمليات نقل بيانات قاعدة بيانات Room، يُرجى الاطّلاع على مقالة نقل بيانات قاعدة بيانات Room.

تعرض الأقسام التالية بعض الأمثلة على طريقة عمل ذلك في الممارسة.

مثال: عملية نقل بيانات احتياطية باستخدام قاعدة بيانات مُعدّة مسبقًا

لنفترض ما يلي:

• يحدّد تطبيقك قاعدة بيانات Room في الإصدار 3.
• إنّ قاعدة بيانات Room المُثبّتة حاليًا على الجهاز هي الإصدار 2.
• هناك ملف قاعدة بيانات مُعدّ مسبقًا في الإصدار 3.
• ليس هناك مسار نقل بيانات تم تنفيذه من الإصدار 2 إلى الإصدار 3.
• عمليات نقل البيانات المدمّرة مفعَّلة.

// Database class definition declaring version 3.
@Database(entities = [SampleEntity::class], version = 3)
abstract class FallbackAppDatabase : RoomDatabase() {
    // ...
}

fun createFallbackDb(appContext: Context) {
    Room.databaseBuilder<FallbackAppDatabase>(appContext, "sample.db")
        .createFromAsset("database/myapp.db")
        .fallbackToDestructiveMigration()
        .build()
}
PrepopulateSnippets.kt

إليك ما يحدث في هذه الحالة:

1. بما أنّ قاعدة البيانات المحدّدة في تطبيقك هي الإصدار 3 وقاعدة البيانات المُثبّتة حاليًا على الجهاز هي الإصدار 2، يجب إجراء عملية نقل بيانات.
2. بما أنّه ليس هناك خطة نقل بيانات تم تنفيذها من الإصدار 2 إلى الإصدار 3، فإنّ عملية نقل البيانات هي عملية نقل بيانات احتياطية.
3. بما أنّك تستخدم دالة أداة الإنشاء fallbackToDestructiveMigration builder ، فإنّ عملية نقل البيانات الاحتياطية هي عملية نقل بيانات مدمّرة. تزيل Room قاعدة بيانات Room المُثبّتة على الجهاز.
4. بما أنّه هناك ملف قاعدة بيانات مُعدّ مسبقًا في الإصدار 3، ستعيد Room إنشاء قاعدة البيانات وتملأها باستخدام محتويات ملف قاعدة البيانات المُعدّ مسبقًا. إذا كان ملف قاعدة البيانات المُعدّ مسبقًا في الإصدار 2، ستحدّد Room أنّه لا يطابق الإصدار المستهدَف ولن تستخدمه لعملية نقل البيانات الاحتياطية.

مثال: عملية نقل بيانات تم تنفيذها باستخدام قاعدة بيانات مُعدّة مسبقًا

لنفترض بدلاً من ذلك أنّ تطبيقك ينفّذ مسار نقل بيانات من الإصدار 2 إلى الإصدار 3:

// Database class definition declaring version 3.
@Database(entities = [SampleEntity::class], version = 3)
abstract class ImplementedAppDatabase : RoomDatabase() {
    // ...
}

// Migration path definition from version 2 to version 3.
val MIGRATION_2_3 = object : Migration(2, 3) {
    override suspend fun migrate(connection: SQLiteConnection) {
        // ...
    }
}

fun createImplementedDb(appContext: Context) {
    Room.databaseBuilder<ImplementedAppDatabase>(appContext, "sample.db")
        .createFromAsset("database/myapp.db")
        .addMigrations(MIGRATION_2_3)
        .build()
}
PrepopulateSnippets.kt

إليك ما يحدث في هذه الحالة:

1. بما أنّ قاعدة البيانات المحدّدة في تطبيقك هي الإصدار 3 وقاعدة البيانات المُثبّتة حاليًا على الجهاز هي الإصدار 2، يجب إجراء عملية نقل بيانات.
2. بما أنّه هناك مسار نقل بيانات تم تنفيذه من الإصدار 2 إلى الإصدار 3، ستنفّذ Room دالة migrate المحدّدة لتعديل قاعدة بيانات Room على الجهاز إلى الإصدار 3، مع الاحتفاظ بالبيانات الموجودة حاليًا في قاعدة البيانات. لا تستخدم Room ملف قاعدة البيانات المُعدّ مسبقًا، لأنّ Room تستخدم ملفات قاعدة البيانات المُعدّة مسبقًا فقط في حال عملية نقل البيانات الاحتياطية.

مثال: عملية نقل بيانات متعددة الخطوات باستخدام قاعدة بيانات مُعدّة مسبقًا

يمكن أن تؤثر ملفات قاعدة البيانات المُعدّة مسبقًا أيضًا في عمليات نقل البيانات التي تتألف من خطوات متعددة. لنفترض الحالة التالية:

• يحدّد تطبيقك قاعدة بيانات Room في الإصدار 4.
• إنّ قاعدة بيانات Room المُثبّتة حاليًا على الجهاز هي الإصدار 2.
• هناك ملف قاعدة بيانات مُعدّ مسبقًا في الإصدار 3.
• هناك مسار نقل بيانات تم تنفيذه من الإصدار 3 إلى الإصدار 4، ولكن ليس من الإصدار 2 إلى الإصدار 3.
• عمليات نقل البيانات المدمّرة مفعَّلة.

// Database class definition declaring version 4.
@Database(entities = [SampleEntity::class], version = 4)
abstract class MultiStepAppDatabase : RoomDatabase() {
    // ...
}

val MIGRATION_3_4 = object : Migration(3, 4) {
    override suspend fun migrate(connection: SQLiteConnection) {
        // ...
    }
}

fun createMultiStepDb(appContext: Context) {
    Room.databaseBuilder<MultiStepAppDatabase>(appContext, "sample.db")
        .createFromAsset("database/myapp.db")
        .addMigrations(MIGRATION_3_4)
        .fallbackToDestructiveMigration()
        .build()
}
PrepopulateSnippets.kt

إليك ما يحدث في هذه الحالة:

1. بما أنّ قاعدة البيانات المحدّدة في تطبيقك هي الإصدار 4 وقاعدة البيانات المُثبّتة حاليًا على الجهاز هي الإصدار 2، يجب إجراء عملية نقل بيانات.
2. بما أنّه ليس هناك مسار نقل بيانات تم تنفيذه من الإصدار 2 إلى الإصدار 3، فإنّ عملية نقل البيانات هي عملية نقل بيانات احتياطية.
3. بما أنّك تستخدم دالة أداة الإنشاء fallbackToDestructiveMigration builder ، فإنّ عملية نقل البيانات الاحتياطية هي عملية نقل بيانات مدمّرة. تزيل Room قاعدة بيانات Room على الجهاز.
4. بما أنّه هناك ملف قاعدة بيانات مُعدّ مسبقًا في الإصدار 3، ستعيد Room إنشاء قاعدة البيانات وتملأها باستخدام محتويات ملف قاعدة البيانات المُعدّ مسبقًا.
5. إنّ قاعدة بيانات Room المُثبّتة على الجهاز هي الآن الإصدار 3. بما أنّها لا تزال أقل من الإصدار المحدّد في تطبيقك، يجب إجراء عملية نقل بيانات أخرى.
6. بما أنّه هناك مسار نقل بيانات تم تنفيذه من الإصدار 3 إلى الإصدار 4، ستنفّذ Room دالة migrate المحدّدة لتعديل قاعدة بيانات Room على الجهاز إلى الإصدار 4، مع الاحتفاظ بالبيانات التي تم نسخها من ملف قاعدة البيانات المُعدّ مسبقًا في الإصدار 3.