AudiOhm/backend/ALEMBIC_GUIDE.md

# Alembic Migration Guide - AudiOhm

## Overview

Ce guide explique comment utiliser les migrations Alembic pour gérer le schéma de base de données AudiOhm.

## Structure

```
backend/
├── alembic.ini                      # Configuration Alembic
├── alembic/
│   ├── env.py                       # Configuration de l'environnement
│   ├── script.py.mako               # Template pour les migrations
│   ├── versions/                    # Dossier des migrations
│   │   └── 001_add_library_tables.py  # Migration initiale
│   └── README                       # Documentation Alembic
```

## Migration Actuelle

### 001_add_library_tables.py

Cette migration crée deux tables pour la fonctionnalité de bibliothèque personnelle:

#### 1. Table `listening_history`
Enregistre l'historique d'écoute des utilisateurs.

**Colonnes:**
- `id` (UUID, PRIMARY KEY): Identifiant unique de l'historique
- `user_id` (UUID, FOREIGN KEY → users.id): Référence à l'utilisateur
- `track_id` (UUID, FOREIGN KEY → tracks.id): Référence à la musique
- `played_for` (INTEGER): Durée d'écoute en secondes
- `completed` (BOOLEAN): Si le morceau a été écouté entièrement
- `source` (VARCHAR(50)): Source de lecture (library, playlist, search, etc.)
- `played_at` (DATETIME): Quand la lecture a eu lieu
- `created_at` (DATETIME): Date de création de l'enregistrement

**Index:**
- `ix_listening_history_id`: Index sur l'ID (recherche rapide)
- `ix_listening_history_user_id`: Index sur user_id (filtrage par utilisateur)
- `ix_listening_history_track_id`: Index sur track_id (filtrage par morceau)
- `ix_listening_history_played_at`: Index sur played_at (tri chronologique)
- `ix_listening_history_user_played`: Index composite (user_id, played_at) pour l'historique
- `ix_listening_history_user_track`: Index composite (user_id, track_id) pour vérifier les doublons

#### 2. Table `liked_tracks`
Enregistre les morceaux aimés/favoris des utilisateurs.

**Colonnes:**
- `id` (UUID, PRIMARY KEY): Identifiant unique
- `user_id` (UUID, FOREIGN KEY → users.id): Référence à l'utilisateur
- `track_id` (UUID, FOREIGN KEY → tracks.id): Référence à la musique
- `notes` (VARCHAR(1000)): Notes personnelles de l'utilisateur sur le morceau
- `created_at` (DATETIME): Date d'ajout aux favoris
- `updated_at` (DATETIME): Date de dernière mise à jour

**Index:**
- `ix_liked_tracks_id`: Index sur l'ID
- `ix_liked_tracks_user_id`: Index sur user_id
- `ix_liked_tracks_track_id`: Index sur track_id
- `ix_liked_tracks_user_track`: Index UNIQUE composite (user_id, track_id) - empêche les doublons

## Commandes Alembic

### Vérifier l'état actuel

```bash
cd /opt/audiOhm/backend
alembic current
```

Affiche la version actuelle de la base de données.

### Voir l'historique des migrations

```bash
alembic history
```

Affiche toutes les migrations et leur ordre.

### Voir les têtes de branches

```bash
alembic heads
```

Affiche les dernières versions de chaque branche.

### Voir les détails d'une migration

```bash
alembic show 001_add_library_tables
```

Affiche les détails d'une migration spécifique.

### Créer une nouvelle migration

```bash
alembic revision -m "Description de la migration"
```

Crée un nouveau fichier de migration vide à éditer manuellement.

### Créer une migration automatique

```bash
alembic revision --autogenerate -m "Description de la migration"
```

Génère automatiquement la migration en comparant les modèles SQLAlchemy avec la base de données.

**Note:** Pour utiliser `--autogenerate`, vous devez installer `psycopg2` ou modifier `env.py` pour utiliser le bon pilote.

### Appliquer les migrations (upgrade)

```bash
# Appliquer toutes les migrations
alembic upgrade head

# Appliquer une migration spécifique
alembic upgrade 001_add_library_tables

# Appliquer les n prochaines migrations
alembic upgrade +1
```

### Annuler les migrations (downgrade)

```bash
# Annuler la dernière migration
alembic downgrade -1

# Annuler jusqu'à la base (tout annuler)
alembic downgrade base

# Annuler jusqu'à une migration spécifique
alembic downgrade <revision_id>
```

### Vérifier le SQL sans l'exécuter

```bash
# Voir le SQL de l'upgrade
alembic upgrade head --sql

# Voir le SQL du downgrade
alembic downgrade -1 --sql
```

## Configuration

### Fichier alembic.ini

Le fichier `/opt/audiOhm/backend/alembic.ini` contient:

- `script_location`: Emplacement des scripts de migration (alembic)
- `sqlalchemy.url`: URL de connexion à la base de données
- `file_template`: Format de nommage des fichiers de migration

### Fichier env.py

Le fichier `/opt/audiOhm/backend/alembic/env.py`:

- Charge les variables d'environnement depuis `.env`
- Importe les modèles SQLAlchemy
- Configure la connexion à la base de données
- Convertit l'URL async en sync pour Alembic

## Utilisation Typique

### Première installation

1. **Assurez-vous que PostgreSQL est installé et configuré**

2. **Créez la base de données:**
   ```bash
   sudo -u postgres psql
   CREATE DATABASE spotify_le_2;
   CREATE USER spotify WITH PASSWORD 'spotify_password';
   GRANT ALL PRIVILEGES ON DATABASE spotify_le_2 TO spotify;
   \q
   ```

3. **Configurez les variables d'environnement:**
   ```bash
   cd /opt/audiOhm/backend
   cp .env.example .env
   # Éditez .env avec vos paramètres
   ```

4. **Appliquez les migrations:**
   ```bash
   cd /opt/audiOhm/backend
   alembic upgrade head
   ```

### Développement

Lorsque vous modifiez les modèles SQLAlchemy:

1. **Créez une nouvelle migration:**
   ```bash
   alembic revision --autogenerate -m "Description des changements"
   ```

2. **Vérifiez le fichier généré:**
   ```bash
   cat alembic/versions/xxx_description.py
   ```

3. **Appliquez la migration:**
   ```bash
   alembic upgrade head
   ```

### Production

1. **Sauvegardez la base de données avant la migration:**
   ```bash
   pg_dump spotify_le_2 > backup_before_migration.sql
   ```

2. **Appliquez les migrations:**
   ```bash
   alembic upgrade head
   ```

3. **Vérifiez que l'application fonctionne toujours**

## Dépannage

### Erreur: "No module named 'psycopg2'"

Alembic essaie d'utiliser psycopg2 par défaut. Pour utiliser asyncpg:

1. Installez psycopg2:
   ```bash
   pip install psycopg2-binary
   ```

2. OU modifiez la migration pour ne pas utiliser de connexions réelles

### Erreur: "No config file 'alembic.ini' found"

Vous n'êtes pas dans le bon répertoire. Exécutez:
```bash
cd /opt/audiOhm/backend
```

### Vérifier si les tables existent

```bash
sudo -u postgres psql spotify_le_2
\dt
SELECT * FROM alembic_version;
\q
```

### Réinitialiser complètement la base de données

```bash
# Supprimer toutes les migrations (DANGER!)
alembic downgrade base

# Supprimer toutes les tables
sudo -u postgres psql spotify_le_2
DROP SCHEMA public CASCADE;
CREATE SCHEMA public;
GRANT ALL ON SCHEMA public TO spotify;
GRANT ALL ON SCHEMA public TO public;
\q

# Réappliquer les migrations
alembic upgrade head
```

## Bonnes Pratiques

1. **Toujours vérifier** le SQL généré avant d'appliquer une migration
2. **Faire des sauvegardes** avant les migrations en production
3. **Tester les migrations** dans un environnement de développement d'abord
4. **Utiliser des transactions** Alembic utilise déjà des transactions automatiques
5. **Documenter** les migrations avec des messages clairs
6. **Ne pas modifier** les migrations déjà appliquées (créez-en une nouvelle)

## Références

- [Documentation Alembic](https://alembic.sqlalchemy.org/)
- [Documentation SQLAlchemy](https://docs.sqlalchemy.org/)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)