Base de données & Migrations
Voici un guide utilisateur clair et pratique pour la fonctionnalité “Base de données & Migrations”. Il explique pourquoi elle existe, ce que vous pouvez faire avec, et comment effectuer les actions courantes pas à pas.
Une base de données centralisée et un système de migrations vous permettent de faire évoluer en sécurité la structure des données (utilisateurs, projets, clés API, journaux, etc.) tout en gardant un historique clair des changements. Les migrations versionnées facilitent les déploiements reproductibles et la coordination entre développeurs, staging et production.
Ce que vous obtenez
Schéma centralisé
Un modèle unique décrit toutes les entités de l’application (utilisateurs, projets, clés API, logs, agents, hooks…). Avantage : cohérence et visibilité sur la structure de vos données.
Migrations versionnées
Chaque modification du schéma génère une migration horodatée et révisable. Avantage : vous pouvez suivre l’historique des évolutions et revenir à un état antérieur si nécessaire.
Génération & validation
Outil pour générer automatiquement le SQL lié à un changement, puis le relire avant exécution. Avantage : réduire les erreurs et comprendre l’impact avant déploiement.
Application contrôlée
Appliquez les migrations dans les environnements (dev → staging → prod) de façon reproductible. Avantage : déploiements prévisibles et audits facilités.
Rollback et sécurité
Possibilité de revenir en arrière en suivant des bonnes pratiques (revert de migration + restauration si nécessaire). Avantage : limiter les risques métier en cas de problème.
Traçabilité et documentation
Chaque migration est accompagnée d’un message ou d’une description expliquant le changement. Avantage : faciliter la revue et la compréhension entre collègues.
Pour qui ?
Cette fonctionnalité s’adresse aux développeurs et aux responsables produit qui doivent faire évoluer les données sans surprises : schema évolutif, déploiements structurés et audits.
:::
How to use it
Suivez ces étapes concrètes pour créer, valider et déployer des migrations. Les étapes couvrent le flux habituel : changement en local, génération, validation, application en staging, puis production.
Étapes principales
1. Planifier la modification
- Décidez précisément quelle entité ou quel champ doit changer (ex : ajouter une information, enregistrer un nouveau type d’événement, gérer des clés API).
- Notez l’impact attendu : données existantes affectées ? migration de données nécessaire ? fenêtre de maintenance ?
- Rédigez une courte description du changement (but + conséquence) à joindre à la migration.
2. Générer la migration (en local)
- Ouvrez votre éditeur de schéma (ou l’outil de gestion de schéma de votre projet).
- Modifiez le modèle de données selon le besoin (ajout/modification d’un champ, nouvelle entité, relation).
- Lancez la commande ou l’action “générer une migration” avec l’outil de migration (outil recommandé : Prisma Migrate). Cela produit une migration versionnée contenant le SQL proposé.
- Ce qui se passe ensuite : vous obtenez un fichier de migration avec un descriptif ; la structure envisagée est produite mais non appliquée encore à votre base.
3. Relire et valider la migration
- Ouvrez la migration générée et vérifiez la description et le SQL proposé (vérifiez contraintes, valeurs par défaut, nullabilité).
- Si vous avez des jeux de tests ou une base de développement, appliquez la migration localement pour valider que tout se passe bien.
- Documentez si la migration nécessite des opérations manuelles (ex : remplissage de nouvelles colonnes pour les enregistrements existants).
4. Commit et pipeline (staging)
- Validez (commit) la migration et la description dans le contrôle de version.
- Déployez sur l’environnement de staging en exécutant l’action d’application des migrations (par ex. via Prisma Migrate deploy).
- Vérifiez le comportement de l’application et exécutez vos tests E2E / intégration.
- Ce qui se passe ensuite : la migration est appliquée en staging ; vous pouvez détecter effets secondaires ou impact sur les temps de réponse.
5. Déploiement en production
- Après validation en staging, planifiez la fenêtre de déploiement en production (prévoir sauvegarde).
- Exécutez l’application des migrations en production via l’outil de migration (ordre habituel : arrêter les tâches sensibles, backup, appliquer, vérifier).
- Confirmez que l’application fonctionne et surveillez les métriques pour détecter toute régression.
6. Rollback / revenir en arrière
- Si un problème bloque la production, ne paniquez pas : restaurez une sauvegarde récente si la migration a corrompu des données critiques.
- Autre option : revert du commit de migration et redéploiement contrôlé (après validation sur un environnement de test).
- Ce qui se passe ensuite : le retour peut nécessiter une restauration des données ; suivez le plan de rollback validé auparavant.
7. Bonnes pratiques quotidiennes
- Faites une migration par modification logique (petite et ciblée).
- Toujours tester en local puis en staging avant la production.
- Documentez chaque migration (objectif + risques + étapes manuelles éventuelles).
- Sauvegarde systématique avant toute migration en production.
Conseil pro
Créez des migrations atomiques : une seule intention par migration (par exemple “ajout d’un champ X” ou “création de l’entité Y”). Cela facilite les revues, le rollback et la traçabilité. Testez toujours en staging avec des données représentatives.
Limites et règles importantes
- Sauvegardez la base avant toute migration en production : certaines modifications sont difficiles à annuler.
- Évitez de combiner plusieurs changements non liés dans une même migration.
- Les modifications qui touchent de grandes tables (ajout d’index, colonnes non-null avec backfill) peuvent être longues et impacter les performances — planifiez une fenêtre de maintenance si nécessaire.
- Ne modifiez pas une migration déjà appliquée publiquement : préférez créer une nouvelle migration corrective.
FAQ
Frequently Asked Questions
Si vous voulez, je peux ajouter une checklist imprimable à chaque déploiement (backup, tests, fenêtre de maintenance, personnes à prévenir) ou un exemple de message de migration à standardiser pour l’équipe. Vous souhaitez cela ?