Guide de migration de base de données Room (partie 1)
Comprendre comment migrer votre base de données Room étape par étape.
Nous allons voir dans cet article les différentes approches de migration d’une base de données Room. Pour commencer, une migration est un moyen de gérer le passage d’une version d’une base de données à une autre comme quand vous publier une nouvelle version de votre application sur Google Play et que vos utilisateurs téléchargent pour remplacer l’ancienne.
⚠️ Cet article suppose que vous êtes déjà familiers avec bases librairie Room sinon, veuillez visiter la documentation pour un bref aperçu de la librairie.
Scenario 📋
Considérons l’entité Fruit définit comme suit:
notre interface FruitDao composée de deux méthodes simples, insertFruit() pour insérer un nouveau fruit dans notre BD, et la méthode fetchFruits() qui retourne une liste des fruits présents dans notre BD.
puis notre classe FruitDatabase, une classe abstraite avec une méthode utilitaire pour créer la base de données . A noter le paramètre version qui indique la version de notre bd (ici version = 1).
Tout est réuni pour insérer dans notre bd autant de fruits que l’on désire, et les afficher au besoin dans une liste mais nos utilisateurs demandent à avoir le nom scientifique de chaque fruit à coté du nom vernaculaire dans la prochaine version de notre application.
Pour ce faire, nous allons naturellement procéder en rajoutant à notre classe Fruit une une propriété scientificName qui prendra le nom scientifique d’un fruit représenté par une chaîne de caractères.
val scientificName: String = “”On relance notre application puis on ajoute dans notre base de données un nouveau fruit avec les attributs name et scientificName.
Résultat ? l’application va crasher avec comme message d’erreur:
Caused by: java.lang.IllegalStateException: Room cannot verify the data integrity. Looks like you've changed schema but forgot to update the version number. You can simply fix this by increasing the version number.Explication: Room ne reconnaît plus le schéma de notre table fruit et nous propose d’augmenter la version de notre bd. Pour ce faire, nous allons modifier l’argument version de notre classe FruitDatabase en passant 2 comme valeur.
Notre base de données est maintenant à la version 2, on relance notre application….un autre crashh 🥺.
java.lang.IllegalStateException: A migration from 1 to 2 was required but not found. Please provide the necessary Migration path via RoomDatabase.Builder.addMigration(Migration …) or allow for destructive migrations via one of the RoomDatabase.Builder.fallbackToDestructiveMigration* methods.Cette fois-ci le message d’erreur nous propose deux options:
- Fournir un chemin de migration de notre base de données par le biais de la méthode addMigrations()
- Permettre à Room de recréer à nouveau les tables base de données en détruisant les données précédentes à l’aide d’une des méthodes de destructions fournies par Room (détails ci après).
Nous allons commencer par l’option de destruction, c.-à-d l’option 2, avant de voir comment fournir un chemin de migration dans le cas ou nous aurons besoin de sauvegarder nos données déjà enregistrées.
- fallbackToDestructiveMigration()
cette méthode “écrase tout” et recrée la table fruits avec notre nouvelle colonne scientificName()
notre application ne va plus crasher , Room a remplacé l’ancienne table pour créer une nouvelle table avec notre colonne a jour.
- fallbackToDestructiveMigrationFrom()
Méthode à nombre variable de paramètres, elle informe Room à recréer de manière destructive des tables à partir de versions spécifiques passées en paramètres. Si jamais il y a migration vers la version 2, 3 ou 4 la destruction est autorisée.
- fallbackToDestructiveMigrationOnDowngrade()
Indique à Room de recréer les tables de manière destructive si un chemin de migration n’est pas indiquée lors d’une rétrogradation vers une ancienne version.
Fournir un chemin de migration
Nous allons voir comment migrer notre base de données de la version 1 a la version 2 tout en conservant nos précédents enregistrements. Pour ce faire nous allons commencer par une ajouter quelque configurations gradle tres utile pour notre migration.
Nous allons rajouter ces quatre lignes dans notre ficher build.gradle (app) qui nous seront essentiels pour tester notre migration.
Une fois le build terminé notre schéma de base de données sera exportée dans le répertoire dans un fichier 1.json (le 1 représente la version de notre base de données)
Nous allons ensuite permettre a notre projet androidTest d’accéder a aux schémas en ajoutant toujours au fichier build.gradle (app)
La configuration terminée, nous pouvons commencer la migration de notre base de données de la version actuelle (1) a la version 2. Appliquons les mêmes changements qu’au tout début — ajoutons un nouveau champ dans notre entité Fruit appelé scientificName et mettons à jour la version de notre base de données à 2. Après un rebuild, nous aurons un nouveau fichier pour 2.json dans le répertoire schemas.
Il est temps de migrer !
Pour migrer notre base de données, nous allons fournir une implémentation de la classe Migration qu’on appellera Migration_1_2 comme le recommande la convention. La classe Migration étant abstraite, nous allons fournir une redéfinition de la méthode migrate() dans laquelle nous exécuterons notre commande SQL.
A noter que la commande que vous mettez ici varie en fonction de la modification apportée a la base de données, ça peut être l’ajoute nouvelle table, un nouveau champ, suppression etc.. Ici nous avons rajouté un nouveau champ scientific_name a notre table fruits.
Enfin nous allons ajouter notre migration en passant Migration_1_2 en paramétres de la méthode addMigrations()
Et.. BINGOO ! la migration de notre base de données de la version 1 a la version 2 a été effectuée avec succès!
Dans la prochaine partie, nous verrons comment effectuer des tests unitaires sur notre base de données afin de valider tout changement.
N’hésitez pas a laisser quelques 👏🏽👏🏽 et a partager !
Bonne lecture !
