LeDiscord/backend/MIGRATIONS.md

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 :

# 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

# 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

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

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.) :

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 :

# 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 !

# 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
• SQLAlchemy Documentation