تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

قد ترغب أحيانًا في أن يبدأ تطبيقك بقاعدة بيانات موجودة بالفعل محملة بمجموعة محددة من البيانات. وهذا ما يُسمّى تعبئة قاعدة البيانات تلقائيًا. في الغرفة 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 ملف قاعدة بيانات مضغوط بشكل مسبق. تنشئ الغرفة نسخة من الملف المحدد بدلاً من عدم فتحه مباشرةً، لذا تأكَّد من أنّ التطبيق لديه أذونات بالقراءة على الملف.

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

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

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

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

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

افترض ما يلي:

يحدِّد تطبيقك قاعدة بيانات الغرف في الإصدار 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();

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

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

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

ولنفرض أنّ تطبيقك ينفِّذ مسار نقل بيانات من الإصدار 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();

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

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

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

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

يحدِّد تطبيقك قاعدة بيانات الغرف في الإصدار 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();

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

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

مصادر إضافية

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

الفيديوهات

الميزات الجديدة في الغرفة (مؤتمر Android Dev Summit 2019)

المدوّنات

تجهيز الغرف: تعبئة قاعدة البيانات مسبقًا بهذه الطريقة

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

نقل قاعدة البيانات