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

cd /opt/audiOhm/backend
alembic current

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

Voir l'historique des migrations

alembic history

Affiche toutes les migrations et leur ordre.

Voir les têtes de branches

alembic heads

Affiche les dernières versions de chaque branche.

Voir les détails d'une migration

alembic show 001_add_library_tables

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

Créer une nouvelle migration

alembic revision -m "Description de la migration"

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

Créer une migration automatique

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)

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

# 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

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

   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:

   cd /opt/audiOhm/backend
   cp .env.example .env
   # Éditez .env avec vos paramètres
   

4. Appliquez les migrations:

   cd /opt/audiOhm/backend
   alembic upgrade head
   

Développement

Lorsque vous modifiez les modèles SQLAlchemy:

1. Créez une nouvelle migration:

   alembic revision --autogenerate -m "Description des changements"
   

2. Vérifiez le fichier généré:

   cat alembic/versions/xxx_description.py
   

3. Appliquez la migration:

   alembic upgrade head
   

Production

1. Sauvegardez la base de données avant la migration:

   pg_dump spotify_le_2 > backup_before_migration.sql
   

2. Appliquez les migrations:

   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:

   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:

cd /opt/audiOhm/backend

Vérifier si les tables existent

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

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

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