139 lines
3.8 KiB
Markdown
139 lines
3.8 KiB
Markdown
# Guide des Migrations Alembic
|
|
|
|
Ce projet utilise Alembic pour gérer les migrations de base de données de manière versionnée et contrôlée.
|
|
|
|
## 🚀 Démarrage rapide
|
|
|
|
### Première utilisation
|
|
|
|
Si c'est la première fois que vous utilisez Alembic sur ce projet :
|
|
|
|
```bash
|
|
# Depuis le conteneur backend
|
|
docker compose exec backend alembic revision --autogenerate -m "Initial migration"
|
|
|
|
# Appliquer la migration
|
|
docker compose exec backend alembic upgrade head
|
|
```
|
|
|
|
### Commandes courantes
|
|
|
|
```bash
|
|
# Créer une nouvelle migration (autogenerate depuis les modèles)
|
|
docker compose exec backend alembic revision --autogenerate -m "Description de la migration"
|
|
|
|
# Appliquer toutes les migrations en attente
|
|
docker compose exec backend alembic upgrade head
|
|
|
|
# Revenir en arrière d'une migration
|
|
docker compose exec backend alembic downgrade -1
|
|
|
|
# Voir la migration actuelle
|
|
docker compose exec backend alembic current
|
|
|
|
# Voir l'historique des migrations
|
|
docker compose exec backend alembic history
|
|
```
|
|
|
|
## 📋 Workflow de développement
|
|
|
|
### 1. Modifier un modèle
|
|
|
|
Éditez les fichiers dans `backend/models/` pour ajouter/modifier des colonnes, tables, etc.
|
|
|
|
### 2. Créer une migration
|
|
|
|
```bash
|
|
docker compose exec backend alembic revision --autogenerate -m "Ajout du champ X à la table Y"
|
|
```
|
|
|
|
Alembic va automatiquement détecter les changements dans vos modèles SQLAlchemy.
|
|
|
|
### 3. Vérifier la migration
|
|
|
|
Ouvrez le fichier généré dans `backend/migrations/versions/` et vérifiez que les changements sont corrects.
|
|
|
|
### 4. Appliquer la migration
|
|
|
|
```bash
|
|
docker compose exec backend alembic upgrade head
|
|
```
|
|
|
|
### 5. Tester
|
|
|
|
Vérifiez que votre application fonctionne correctement avec les nouvelles migrations.
|
|
|
|
## ⚠️ Notes importantes
|
|
|
|
- **Ne modifiez jamais manuellement** les fichiers de migration existants qui ont déjà été appliqués
|
|
- **Toujours tester** les migrations en développement avant de les appliquer en production
|
|
- **Sauvegardez votre base de données** avant d'appliquer des migrations en production
|
|
- Les migrations sont **versionnées** : chaque migration a un ID unique et un historique
|
|
|
|
## 🔄 Migration manuelle (sans autogenerate)
|
|
|
|
Si vous avez besoin de créer une migration manuelle (pour des données, des index complexes, etc.) :
|
|
|
|
```bash
|
|
docker compose exec backend alembic revision -m "Description"
|
|
```
|
|
|
|
Puis éditez le fichier généré dans `backend/migrations/versions/` pour ajouter votre logique.
|
|
|
|
## 🐛 Dépannage
|
|
|
|
### Migration en conflit
|
|
|
|
Si vous avez des conflits de migration :
|
|
|
|
```bash
|
|
# Voir l'état actuel
|
|
docker compose exec backend alembic current
|
|
|
|
# Voir l'historique
|
|
docker compose exec backend alembic history
|
|
|
|
# Revenir à une version spécifique
|
|
docker compose exec backend alembic downgrade <revision_id>
|
|
```
|
|
|
|
### Migration qui échoue
|
|
|
|
Si une migration échoue :
|
|
|
|
1. Vérifiez les logs : `docker compose logs backend`
|
|
2. Vérifiez l'état de la base : `docker compose exec backend alembic current`
|
|
3. Si nécessaire, corrigez la migration et réessayez
|
|
|
|
### Réinitialiser les migrations (⚠️ DANGEREUX)
|
|
|
|
**ATTENTION** : Cela supprime toutes les données !
|
|
|
|
```bash
|
|
# Supprimer toutes les tables
|
|
docker compose exec backend alembic downgrade base
|
|
|
|
# Recréer depuis le début
|
|
docker compose exec backend alembic upgrade head
|
|
```
|
|
|
|
## 📁 Structure des fichiers
|
|
|
|
```
|
|
backend/
|
|
├── alembic.ini # Configuration Alembic
|
|
├── migrations/
|
|
│ ├── env.py # Configuration de l'environnement
|
|
│ ├── script.py.mako # Template pour les migrations
|
|
│ ├── versions/ # Fichiers de migration (générés)
|
|
│ └── README.md # Documentation
|
|
└── models/ # Modèles SQLAlchemy
|
|
```
|
|
|
|
## 🔗 Ressources
|
|
|
|
- [Documentation Alembic](https://alembic.sqlalchemy.org/)
|
|
- [SQLAlchemy Documentation](https://docs.sqlalchemy.org/)
|
|
|
|
|