# 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/)