Alembic – migrations de base de données

Introduction

Le développement d'applications web modernes implique inévitablement l'évolution de la structure de la base de données. Ajout de nouvelles tables, modification des types de données, création d'index et ajustement des relations entre entités — tout cela nécessite une approche systématique de la gestion. Effectuer ces modifications manuellement expose à des erreurs, des pertes de données et des incohérences entre les environnements de développement.

Alembic est un outil puissant pour gérer les migrations de bases de données, spécialement conçu pour l'écosystème SQLAlchemy. C'est la solution officielle qui permet de modifier la structure de la base de données de manière sécurisée et contrôlée, en offrant aux développeurs la possibilité de suivre l'historique des changements, d'appliquer des mises à jour et, si nécessaire, d'annuler des modifications problématiques.

Qu'est-ce qu'Alembic

Alembic est une bibliothèque de gestion des migrations de bases de données pour les projets Python utilisant SQLAlchemy. Elle fournit des outils pour créer, appliquer et annuler des modifications du schéma de base de données de manière ordonnée et contrôlée.

Les principaux avantages d'Alembic

Versionnement du schéma de base de données — chaque modification est enregistrée sous forme d'une migration unique avec un identifiant distinct, permettant de suivre l'évolution de la structure des données.

Génération automatique des migrations — possibilité de créer des fichiers de migration à partir des modifications apportées aux modèles ORM SQLAlchemy, ce qui accélère considérablement le développement.

Sécurité des opérations — toutes les modifications sont appliquées dans le cadre de transactions, minimisant ainsi les risques de corruption des données.

Prise en charge de plusieurs SGBD — fonctionne avec PostgreSQL, MySQL, SQLite, Oracle et d'autres bases de données prises en charge par SQLAlchemy.

Installation et configuration d'Alembic

Installation du paquet

pip install alembic

Pour les applications asynchrones, installez également les dépendances supplémentaires :

pip install alembic[asyncio]

Initialisation du projet de migrations

Après l'installation, initialisez la structure du projet :

alembic init alembic

Cette commande crée la structure de fichiers suivante :

alembic/
├── versions/           # Répertoire pour les fichiers de migration
├── env.py             # Configuration de l'environnement
├── script.py.mako     # Modèle pour la génération des migrations
└── alembic.ini        # Fichier de configuration principal

Configuration de la connexion à la base de données

Dans le fichier alembic.ini, indiquez la chaîne de connexion à la base de données :

sqlalchemy.url = postgresql://utilisateur:motdepasse@localhost/nom_base

Vous pouvez également configurer la connexion par programmation dans le fichier env.py :

from sqlalchemy import create_engine
from monprojet.config import DATABASE_URL

config.set_main_option("sqlalchemy.url", DATABASE_URL)

Intégration avec SQLAlchemy

Connexion des modèles

Pour que l'auto-génération des migrations fonctionne correctement, vous devez spécifier les métadonnées des modèles dans le fichier alembic/env.py :

from mesmodeles.models import Base

# Spécifiez les métadonnées pour l'auto-génération
target_metadata = Base.metadata

Exemple de modèle de base

from sqlalchemy import Column, Integer, String, DateTime, Boolean
from sqlalchemy.ext.declarative import declarative_base
from datetime import datetime

Base = declarative_base()

class Utilisateur(Base):
    __tablename__ = 'utilisateurs'
    
    id = Column(Integer, primary_key=True)
    nom_utilisateur = Column(String(50), unique=True, nullable=False)
    email = Column(String(100), unique=True, nullable=False)
    est_actif = Column(Boolean, default=True)
    date_inscription = Column(DateTime, default=datetime.utcnow)

    def __repr__(self):
        return f"<Utilisateur(nom_utilisateur='{self.nom_utilisateur}', email='{self.email}')>"