Apprendre Prisma : Migrations avec Prisma Migrate

Qu’est-ce qu’une migration ?

Dans un ORM, les migrations sont centrales.

Il s’agit d’un processus de contrôle visant à synchroniser le schéma de données de l’application (défini ici dans 📄 schema.prisma) avec la structure du schéma de base de données.

Elles contribuent ainsi à la bonne évolution de votre modèle de données au fur et à mesure du développement de votre application.

Ce changement d’état peut être caractérisé par :

• L’ajout d’une table
• La modification d’une colonne
• L’ajout d’une contrainte relationnelle
• La suppression d’un champ
• Etc.

Prisma Migrate vous met également en garde si une migration est potentiellement amenée à supprimer des données de la base. Ce qui est par exemple le cas si je décide de supprimer une colonne d’une table.

Générer et exécuter les migrations

Dans un environnement de développement, pour générer une migration Prisma, on exécute la commande :

npx prisma migrate dev

Cette commande vous demandera de nommer votre migration en décrivant brièvement ce qu’elle fait. Exemple : « Remove title from Post ».

Il est aussi possible de spécifier ce nom en amont, via un argument --name, suivi du nom de la migration :

npx prisma migrate dev --name "Remove title from Post"

Cette commande effectue 2 grandes actions :

1. Elle créé un fichier .sql pour la migration courante.
2. Elle exécute la migration dans la base de données.

Notez qu’il est possible de demander à Prisma de ne pas exécuter cette migration automatiquement avec l’option --create-only (cela peut être utile si vous souhaitez y apporter des modifications manuelles en amont). Ensuite, il faudra à nouveau taper npx prisma migrate dev pour exécuter la migration.

Vous pouvez désormais constater que votre base de données a été créée et que son schéma correspond à celui que vous avez déclaré dans le fichier 📄 schema.prisma.

Historique de migrations

Dossier 📂 prisma

Les migrations sont accessibles au sein du dossier 📂 prisma/migrations. Ce dossier est le garant du stockage de l’historique de vos migrations.

À chaque migration générée, sont créés :

1. Un dossier portant le nom 📂 {date_migration}_{nom_migration}. Exemple : 📂 20230224231120_remove_title_from_post
2. Un fichier 📄 migration.sql contenant le script SQL effectuant les modifications pour faire passer la base de données dans le nouvel état.

ALTER TABLE `post` DROP COLUMN `title`;

Table _prisma_migrations

À chaque migration exécutée, Prisma va logger un ensemble de métadonnées relatives à cette dernière, au sein d’une table _prisma_migrations de la base de données. Voici sa structure :

Chaque entrée de cette table correspond à un fichier de migration .sql.

Son rôle est de vérifier :

• Si une migration a été exécutée en base de données
• Si une migration a été supprimée
• Si une migration a été modifiée

Shadow database : un garde-fou

La base de données fantôme de Prisma, ou « Shadow Database », est une base de données secondaire qui est créée en complément de la base de données principale utilisée par l’application. Elle est utilisée afin de capturer tous les changements de données à effectuer sur la base de données principale, afin que les développeurs puissent analyser et tester ces changements sans affecter la base de données principale elle-même.

En d’autres termes, chaque fois qu’une opération de modification de données (création, mise à jour ou suppression) est à effectuer dans la base de données principale, cette opération est en amont répliquée dans la Shadow Database.

Concrètement, à chaque exécution de la commande npx prisma migrate dev :

1. Une base de données fantôme est créée.

2. L’historique de migrations existant est exécuté sur la base de données fantôme.

3. Par le processus d’introspection, la structure de la base de données fantôme est comparée avec la structure de la base de données de développement.

4. • Si un écart de schéma est relevé (fichier de migration modifié ou supprimé, ou modifications manuelles du schéma de la base de données) : une erreur est générée informant qu’il est nécessaire de réinitialiser le schéma de la base de données pour continuer.
   • Si aucun écart de schéma n’est relevé : le schéma Prisma courant de l’application est comparé avec celui de la base de données fantôme dans le but de générer le fichier de migration .sql implémentant le changement d’état. Si l’option --create-only n’a pas été ajoutée à la commande npx prisma migrate dev, alors la migration est appliquée en base de données et la table _prisma_migrations est mise à jour.

5. La base de données fantôme est supprimée.