Raumdatenbank vorab ausfüllen

Manchmal möchten Sie vielleicht, dass Ihre Anwendung mit einer Datenbank beginnt, die bereits mit einem bestimmten Dataset geladen werden. Dies wird als Vorabfüllen einer Datenbank bezeichnet. In Raum 2.2.0 und höher können Sie API-Methoden verwenden, um eine Raumdatenbank vorab auszufüllen. mit Inhalten aus einer vorkonfigurierten Datenbankdatei im Dateisystem.

Hinweis: In-Memory Room-Datenbanken unterstützen das Vorabfüllen der Datenbank nicht. mit createFromAsset() oder createFromFile().

Mit App-Asset vorausfüllen

Zum Vorabfüllen einer Raumdatenbank aus einer vorkonfigurierten Datenbankdatei, Rufen Sie an einer beliebigen Stelle im Verzeichnis assets/ Ihrer Anwendung die Methode createFromAsset() auf. aus dem RoomDatabase.Builder-Objekt aus, bevor Sie build() aufrufen:

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();

Die Methode createFromAsset() akzeptiert ein Stringargument, das einen relativen Pfad vom Verzeichnis assets/ zur vorkonfigurierten Datenbankdatei.

Hinweis: Beim Vorabfüllen aus einem Asset validiert Room die Datenbank, um sicherzustellen, dass ihr Schema mit dem Schema der vorkonfigurierten Datenbank übereinstimmt. Sie sollten Exportieren Sie das Schema Ihrer Datenbank, um es beim Erstellen der Datenbank als Referenz zu verwenden. vorgefertigte Datenbankdatei.

Aus dem Dateisystem vorausfüllen

Zum Vorabfüllen einer Raumdatenbank aus einer vorkonfigurierten Datenbankdatei, an einer beliebigen Stelle im Dateisystem des Geräts, außer im assets/-Verzeichnis der App, Rufen Sie die Methode createFromFile() aus Ihrem RoomDatabase.Builder-Objekt auf. bevor Sie build() aufrufen:

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();

Die Methode createFromFile() akzeptiert ein File-Argument für den bereits gepackte Datenbankdatei. Der Chatroom erstellt eine Kopie der dafür vorgesehenen Datei, als direktes Öffnen. Achten Sie also darauf, dass Ihre App Leseberechtigungen auf der -Datei.

Hinweis: Beim Vorabausfüllen aus dem Dateisystem validiert Room die Datenbank, um um sicherzustellen, dass ihr Schema dem Schema der vorkonfigurierten Datenbank entspricht. Ich Sie sollten das Schema Ihrer Datenbank exportieren, um es beim Erstellen als Referenz zu verwenden der vorkonfigurierten Datenbankdatei.

Migrationen mit vorkonfigurierten Datenbanken verarbeiten

Vorgefertigte Datenbankdateien können auch die Art und Weise ändern, wie Ihre Room-Datenbank verarbeitet Fallback-Migrationen. Normalerweise, wenn destruktive Migrationen aktiviert sind und „Room“ muss eine Migration ohne Migration ausführen löscht Room alle Tabellen in der Datenbank und erstellt eine leere Datenbank mit Das angegebene Schema für die Zielversion Wenn Sie jedoch ein vorgefertigte Datenbankdatei mit derselben Nummer wie die Zielversion, versucht, die neu erstellte Datenbank mit dem vorgefertigte Datenbankdatei nach der Durchführung der destruktiven Migration.

Weitere Informationen zu Migrationen von Raumdatenbanken finden Sie unter Raum migrieren Datenbanken.

In den folgenden Abschnitten finden Sie einige Beispiele dafür, wie dies in der Praxis funktioniert.

Beispiel: Fallback-Migration mit einer vorkonfigurierten Datenbank

Angenommen,

• Deine App definiert eine Raumdatenbank in Version 3.
• Die bereits auf dem Gerät installierte Datenbankinstanz hat Version 2.
• Es gibt eine vorkonfigurierte Datenbankdatei in Version 3.
• Es ist kein Migrationspfad von Version 2 zu Version 3 implementiert.
• Destruktive Migrationen sind aktiviert.

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();

In dieser Situation geschieht Folgendes:

1. Weil die in Ihrer App definierte Datenbank Version 3 hat und die Datenbank bereits auf dem Gerät installierte Instanz die Version 2 hat, ist eine Migration notwendig ist.
2. Da kein Migrationsplan von Version 2 zu Version 3 implementiert ist, ist die Migration eine Fallback-Migration.
3. Da die Builder-Methode fallbackToDestructiveMigration() aufgerufen wird, ist die Fallback-Migration destruktiv. Die Datenbank wird gelöscht. die auf dem Gerät installiert ist.
4. Da es eine vorkonfigurierte Datenbankdatei in Version 3 gibt, erstellt die Datenbank neu und füllt sie mit dem Inhalt der Datenbankdatei. Wenn Ihre vorkonfigurierte Datenbankdatei hingegen Version 2 enthält, wird „Room“ feststellen, dass die Version nicht mit der Zielversion übereinstimmt. nicht im Rahmen der Fallback-Migration verwendet.

Beispiel: Implementierte Migration mit einer vorkonfigurierten Datenbank

Angenommen, Ihre Anwendung implementiert einen Migrationspfad von Version 2 zu Version 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();

In dieser Situation geschieht Folgendes:

1. Weil die in Ihrer App definierte Datenbank Version 3 hat und die Datenbank bereits auf dem Gerät installiert ist und die Version 2 hat, ist eine Migration erforderlich.
2. Da ein Migrationspfad von Version 2 zu Version 3 implementiert ist, Der Raum führt die definierte Methode migrate() aus, um die Datenbank zu aktualisieren Instanz auf dem Gerät auf Version 3, wobei die bereits vorhandenen Daten in der Datenbank. Room nutzt nicht die vorkonfigurierte Datenbankdatei, verwendet vorgefertigte Datenbankdateien nur im Fall einer Fallback-Migration.

Beispiel: Mehrstufige Migration mit einer vorkonfigurierten Datenbank

Vorgefertigte Datenbankdateien können auch Migrationen beeinflussen, die aus mehreren Schritte. Betrachten Sie den folgenden Fall:

• Deine App definiert eine Raumdatenbank auf Version 4.
• Die bereits auf dem Gerät installierte Datenbankinstanz hat Version 2.
• Es gibt eine vorkonfigurierte Datenbankdatei in Version 3.
• Es gibt einen implementierten Migrationspfad von Version 3 zu Version 4, aber keinen von Version 2 auf Version 3.
• Destruktive Migrationen sind aktiviert.

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();

In dieser Situation geschieht Folgendes:

1. Weil die in Ihrer App definierte Datenbank Version 4 hat und die Datenbank bereits auf dem Gerät installierte Instanz die Version 2 hat, ist eine Migration notwendig ist.
2. Da kein Migrationspfad von Version 2 zu Version 3 implementiert ist, ist die Migration eine Fallback-Migration.
3. Da die Builder-Methode fallbackToDestructiveMigration() aufgerufen wird, ist die Fallback-Migration destruktiv. Die Datenbank wird gelöscht. auf dem Gerät.
4. Da es eine vorkonfigurierte Datenbankdatei in Version 3 gibt, erstellt die Datenbank neu und füllt sie mit dem Inhalt Datenbankdatei.
5. Die auf dem Gerät installierte Datenbank verfügt jetzt über Version 3. Da dies ein immer noch niedriger als die in Ihrer App definierte Version ist, erfolgt eine weitere Migration notwendig ist.
6. Da ein Migrationspfad von Version 3 zu Version 4 implementiert ist, Der Raum führt die definierte Methode migrate() aus, um die Datenbank zu aktualisieren Instanz auf dem Gerät auf Version 4, wobei die kopierten Daten erhalten bleiben aus der vorkonfigurierten Datenbankdatei der Version 3.

Weitere Informationen

Weitere Informationen zum Vorabfüllen einer Raumdatenbank finden Sie in den folgenden zusätzlichen Ressourcen.

Videos

• Neue Funktionen (Android Dev Summit '19)

Blogs

• Der Raum packen: Ihre Datenbank mit dieser einen Methode vorab füllen