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

في بعض الأحيان، قد ترغب في أن يبدأ تطبيقك بقاعدة بيانات محملة بالفعل بمجموعة محددة من البيانات. وتسمى هذه العملية الملء المسبق لقاعدة البيانات. في الغرفة 2.2.0 والإصدارات الأحدث، يمكنك استخدام طرق واجهة برمجة التطبيقات لتعبئة قاعدة بيانات الغرفة مسبقًا عند التهيئة بمحتوى من ملف قاعدة بيانات تم تجميعه مسبقًا في نظام ملفات الجهاز.

التعبئة تلقائيًا من مادة عرض تطبيق

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

Kotlin

Room.databaseBuilder(appContext, AppDatabase::class.java, "Sample.db")
    .createFromAsset("database/myapp.db")
    .build()

Java

Room.databaseBuilder(appContext, AppDatabase.class, "Sample.db")
    .createFromAsset("database/myapp.db")
    .build();

تقبل الطريقة createFromAsset() وسيطة سلسلة تحتوي على مسار نسبي من الدليل assets/ إلى ملف قاعدة البيانات الذي تم تجميعه مسبقًا.

التعبئة تلقائيًا من نظام الملفات

لتعبئة قاعدة بيانات غرفة مسبقًا من ملف قاعدة بيانات مجمّع مسبقًا موجود في أي مكان في نظام ملفات الجهاز باستثناء دليل assets/ في تطبيقك، استدع طريقة createFromFile() من كائن RoomDatabase.Builder قبل طلب build():

Kotlin

Room.databaseBuilder(appContext, AppDatabase::class.java, "Sample.db")
    .createFromFile(File("mypath"))
    .build()

Java

Room.databaseBuilder(appContext, AppDatabase.class, "Sample.db")
    .createFromFile(new File("mypath"))
    .build();

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

معالجة عمليات نقل البيانات التي تتضمّن قواعد بيانات سبقت تعبئتها

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

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

تقدم الأقسام التالية بعض الأمثلة التي توضّح كيفية تطبيق ذلك عمليًا.

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

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

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

Kotlin

// Database class definition declaring version 3.
@Database(version = 3)
abstract class AppDatabase : RoomDatabase() {
    ...
}

// Destructive migrations are enabled and a prepackaged database
// is provided.
Room.databaseBuilder(appContext, AppDatabase::class.java, "Sample.db")
    .createFromAsset("database/myapp.db")
    .fallbackToDestructiveMigration()
    .build()

Java

// Database class definition declaring version 3.
@Database(version = 3)
public abstract class AppDatabase extends RoomDatabase {
    ...
}

// Destructive migrations are enabled and a prepackaged database
// is provided.
Room.databaseBuilder(appContext, AppDatabase.class, "Sample.db")
    .createFromAsset("database/myapp.db")
    .fallbackToDestructiveMigration()
    .build();

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

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

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

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

Kotlin

// Database class definition declaring version 3.
@Database(version = 3)
abstract class AppDatabase : RoomDatabase() {
    ...
}

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

// A prepackaged database is provided.
Room.databaseBuilder(appContext, AppDatabase::class.java, "Sample.db")
    .createFromAsset("database/myapp.db")
    .addMigrations(MIGRATION_2_3)
    .build()

Java

// Database class definition declaring version 3.
@Database(version = 3)
public abstract class AppDatabase extends RoomDatabase {
    ...
}

// Migration path definition from version 2 to version 3.
static final Migration MIGRATION_2_3 = new Migration(2, 3) {
    @Override
    public void migrate(SupportSQLiteDatabase database) {
        ...
    }
};

// A prepackaged database is provided.
Room.databaseBuilder(appContext, AppDatabase.class, "Sample.db")
    .createFromAsset("database/myapp.db")
    .addMigrations(MIGRATION_2_3)
    .build();

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

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

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

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

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

Kotlin

// Database class definition declaring version 4.
@Database(version = 4)
abstract class AppDatabase : RoomDatabase() {
    ...
}

// Migration path definition from version 3 to version 4.
val MIGRATION_3_4 = object : Migration(3, 4) {
    override fun migrate(database: SupportSQLiteDatabase) {
        ...
    }
}

// Destructive migrations are enabled and a prepackaged database is
// provided.
Room.databaseBuilder(appContext, AppDatabase::class.java, "Sample.db")
    .createFromAsset("database/myapp.db")
    .addMigrations(MIGRATION_3_4)
    .fallbackToDestructiveMigration()
    .build()

Java

// Database class definition declaring version 4.
@Database(version = 4)
public abstract class AppDatabase extends RoomDatabase {
    ...
}

// Migration path definition from version 3 to version 4.
static final Migration MIGRATION_3_4 = new Migration(3, 4) {
    @Override
    public void migrate(SupportSQLiteDatabase database) {
        ...
    }
};

// Destructive migrations are enabled and a prepackaged database is
// provided.
Room.databaseBuilder(appContext, AppDatabase.class, "Sample.db")
    .createFromAsset("database/myapp.db")
    .addMigrations(MIGRATION_3_4)
    .fallbackToDestructiveMigration()
    .build();

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

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

مراجع إضافية

لمعرفة المزيد من المعلومات حول التعبئة التلقائية لقاعدة بيانات الغرفة، يُرجى الاطّلاع على الموارد الإضافية التالية.

الفيديوهات الطويلة

المدوّنات

السابق
إنشاء جداول بيانات في قاعدة بيانات
التالي
نقل قاعدة البيانات