Alembic : gérer les migrations SQLAlchemy en Python

Alembic est l'outil de migration de schéma officiel de SQLAlchemy. Il versionne l'évolution de votre base de données : chaque changement de modèle (ajout de colonne, nouvelle table) devient un script de migration horodaté, applicable avec upgrade et réversible avec downgrade. Vous faites ainsi évoluer une base en production sans la recréer ni perdre de données.

Ce guide fait suite à la première partie sur SQLAlchemy et se concentre sur la pratique : installer Alembic, l'initialiser dans un projet, générer des migrations automatiquement, les appliquer, les annuler et adopter les bons réflexes en équipe. Tout le cycle a été exécuté avec Alembic 1.18 sur une base SQLite.

Ce que vous allez apprendre

• Installer et initialiser Alembic dans un projet SQLAlchemy existant.
• Relier Alembic à vos modèles via env.py et alembic.ini.
• Générer une migration automatiquement avec --autogenerate.
• Appliquer, annuler et inspecter les migrations (upgrade, downgrade, history).
• Éviter les pièges de l'autogénération et sécuriser les migrations en production.

Qu'est-ce qu'une migration et pourquoi Alembic

Une migration est un changement contrôlé du schéma d'une base : ajouter une colonne, créer une table, modifier un type. Le problème, c'est que Base.metadata.create_all() de SQLAlchemy ne crée que les tables absentes et n'altère jamais l'existant. Dès qu'une base contient des données réelles, recréer les tables n'est plus envisageable : il faut modifier le schéma en place, sans rien perdre.

Alembic répond exactement à ce besoin. Écrit par l'auteur de SQLAlchemy, il transforme chaque évolution en un script versionné que vous stockez dans Git à côté de votre code. Chaque environnement (poste de développement, préproduction, production) applique la même suite de migrations dans le même ordre, ce qui garantit des schémas identiques partout. En cas d'erreur, vous disposez d'un chemin de retour explicite.

Prérequis

Avant de commencer, vous devez avoir :

• Python 3.10 ou supérieur et un environnement virtuel actif.
• Un projet SQLAlchemy fonctionnel, comme celui de la première partie.
• Des notions de modèles SQLAlchemy (DeclarativeBase, Mapped).

Installer Alembic

Alembic s'installe via pip. Il tire SQLAlchemy comme dépendance, mais autant l'installer explicitement :

pip install alembic sqlalchemy

Vérifiez la version. La sortie doit afficher un numéro 1.x :

alembic --version
# alembic 1.18.5

Le projet SQLAlchemy de départ

Pour illustrer, partons d'un modèle minimal dans un fichier models.py, en syntaxe SQLAlchemy 2.0 :

models.py

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(nullable=False)

C'est ce modèle qu'Alembic va comparer à la base pour détecter les changements. Notez que nous ne créons pas la table à la main : c'est désormais le rôle des migrations.

Initialiser Alembic

À la racine du projet, une seule commande met en place toute la structure :

alembic init alembic

Elle crée un dossier alembic/ et un fichier de configuration :

• Répertoiremon_projet/

  • Répertoirealembic/

    • Répertoireversions/

      • …
    • env.py
    • script.py.mako
    • README
  • alembic.ini
  • models.py

Trois éléments comptent :

• alembic.ini : la configuration principale, dont l'URL de la base.
• alembic/env.py : le script qui relie Alembic à vos modèles.
• alembic/versions/ : le dossier où seront écrits les scripts de migration.

Configurer la connexion et les modèles

Alembic ne connaît ni votre base ni vos modèles tant que vous ne les lui indiquez pas. Deux réglages sont nécessaires.

1. Indiquer l'URL de la base dans alembic.ini. Repérez la ligne sqlalchemy.url et renseignez votre base SQLite :

   sqlalchemy.url = sqlite:///example.db

2. Pointer Alembic vers vos modèles dans alembic/env.py. Remplacez la ligne target_metadata = None par l'import de votre Base :

   from models import Base
   target_metadata = Base.metadata

3. Activer le mode batch pour SQLite. Toujours dans env.py, ajoutez render_as_batch=True à l'appel context.configure de la fonction run_migrations_online :

   with connectable.connect() as connection:
       context.configure(
           connection=connection,
           target_metadata=target_metadata,
           render_as_batch=True,
       )

render_as_batch est indispensable sur SQLite

SQLite ne supporte quasiment pas ALTER TABLE : impossible de supprimer ou de modifier une colonne directement. Sans render_as_batch=True, toute migration qui touche une colonne existante échoue sur SQLite. Le mode batch contourne la limite en recréant la table puis en recopiant les données. PostgreSQL et MySQL n'en ont pas besoin, mais le laisser actif ne pose pas de problème.

Générer la première migration

Alembic sait maintenant comparer vos modèles à l'état réel de la base. La commande --autogenerate produit le script correspondant :

alembic revision --autogenerate -m "initial"

La sortie confirme la détection de la table :

INFO  [alembic.autogenerate.compare.tables] Detected added table 'users'
Generating .../alembic/versions/7cac93520a2c_initial.py ... done

Le script généré dans alembic/versions/ décrit la création de la table. La fonction upgrade() applique le changement, downgrade() l'annule :

"""initial

Revision ID: 7cac93520a2c
Revises:
Create Date: 2026-07-01 19:34:52
"""
from alembic import op
import sqlalchemy as sa

revision = "7cac93520a2c"
down_revision = None


def upgrade() -> None:
    op.create_table(
        "users",
        sa.Column("id", sa.Integer(), nullable=False),
        sa.Column("name", sa.String(), nullable=False),
        sa.PrimaryKeyConstraint("id"),
    )


def downgrade() -> None:
    op.drop_table("users")

Appliquer la migration

Pour synchroniser la base avec le script, appliquez toutes les migrations jusqu'à la plus récente (head) :

alembic upgrade head

INFO  [alembic.runtime.migration] Running upgrade  -> 7cac93520a2c, initial

La table users existe désormais, et Alembic a créé une table technique alembic_version qui mémorise la révision courante de la base.

Faire évoluer le schéma

Le vrai intérêt d'Alembic apparaît quand le modèle change. Ajoutons un champ email à User :

class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(nullable=False)
    email: Mapped[str | None] = mapped_column(default=None)   # nouveau champ

On génère une nouvelle migration. Alembic détecte la colonne ajoutée :

alembic revision --autogenerate -m "add email"

INFO  [alembic.autogenerate.compare.tables] Detected added column 'users.email'

Grâce au mode batch, le script utilise op.batch_alter_table, la forme compatible SQLite :

def upgrade() -> None:
    with op.batch_alter_table("users", schema=None) as batch_op:
        batch_op.add_column(sa.Column("email", sa.String(), nullable=True))


def downgrade() -> None:
    with op.batch_alter_table("users", schema=None) as batch_op:
        batch_op.drop_column("email")

Un alembic upgrade head applique la modification. La colonne email est bien présente dans la table users.

Relisez toujours le script autogénéré

L'autogénération ne détecte pas tout. Un renommage de colonne est vu comme une suppression suivie d'un ajout : appliqué tel quel, il efface les données de l'ancienne colonne. Alembic ignore aussi certaines valeurs par défaut côté serveur et des changements de type subtils. Relisez et corrigez chaque script avant de l'appliquer, surtout sur une base contenant des données réelles.

Annuler une migration

Si une migration pose problème, downgrade exécute sa fonction downgrade() pour revenir en arrière :

alembic downgrade -1              # annule la dernière migration
alembic downgrade 7cac93520a2c    # revient à une révision précise
alembic downgrade base            # revient à une base vide

Après un downgrade -1 sur notre exemple, la colonne email disparaît et la base retrouve son schéma précédent.

Le downgrade détruit des données

Annuler un add_column supprime la colonne et tout ce qu'elle contenait. En développement, c'est pratique ; en production, un downgrade est rarement sûr. Préférez presque toujours une nouvelle migration corrective qui avance dans l'histoire plutôt qu'un retour en arrière destructeur.

Inspecter l'état des migrations

Deux commandes donnent une vue claire de la situation :

alembic history      # la chaîne complète des révisions
alembic current      # la révision appliquée sur la base

La sortie de history montre l'enchaînement des révisions, de la base jusqu'au head :

7cac93520a2c -> 5202795bdd97 (head), add email
<base> -> 7cac93520a2c, initial

Bonnes pratiques et sécurité

Alembic est puissant, mais quelques réflexes évitent les incidents en équipe et en production.

• Relire chaque script autogénéré. L'autogénération est une aide, pas une vérité : elle rate les renommages et certains types. La revue est obligatoire.
• Ne jamais autogénérer contre la production. On génère et on relit en développement, on versionne dans Git, puis la production n'exécute que alembic upgrade head, idéalement depuis la CI/CD.
• Sauvegarder avant de migrer une base réelle. Une migration destructrice sans sauvegarde est irréversible.
• Sortir l'URL de production du fichier. Ne stockez pas l'URL de la base de production en clair dans alembic.ini : lisez-la depuis une variable d'environnement dans env.py (os.environ["DATABASE_URL"]).
• Nommer les migrations clairement (-m "add email field to users") et les committer avec le code applicatif correspondant, pour que chaque déploiement reste cohérent.
• Résoudre les conflits de branches. Quand deux personnes créent une migration en parallèle, deux révisions partagent le même parent. alembic merge crée une révision de fusion pour réunir les deux branches.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• Une migration modifie le schéma en place, sans recréer la base ni perdre les données.
• Alembic versionne ces changements en scripts stockés dans Git, appliqués à l'identique dans chaque environnement.
• Le cycle de base : alembic init, configurer alembic.ini et env.py, puis revision --autogenerate et upgrade head.
• render_as_batch=True est indispensable sur SQLite pour modifier une colonne existante.
• L'autogénération relit obligatoirement : un renommage mal détecté efface des données.
• En production, on applique seulement des migrations relues et testées, après sauvegarde ; le downgrade est rarement sûr.
• alembic history et alembic current donnent l'état des révisions.

FAQ : Alembic et les migrations

Qu'est-ce qu'Alembic et à quoi sert-il ?

Alembic est l'outil de migration de schéma officiel de SQLAlchemy. Il versionne l'évolution de votre base : chaque changement de modèle devient un script de migration horodaté, applicable et réversible. On fait ainsi évoluer une base en production sans la recréer ni perdre de données.

Comment installer et initialiser Alembic ?

Installez-le avec pip install alembic, puis lancez alembic init alembic à la racine du projet. La commande crée le dossier alembic/ (avec env.py et versions/) et le fichier alembic.ini. Il reste à renseigner l'URL de la base et à pointer target_metadata vers vos modèles.

Comment générer une migration automatiquement avec Alembic ?

Une fois env.py relié à vos modèles, lancez alembic revision --autogenerate -m "description". Alembic compare vos modèles SQLAlchemy à l'état réel de la base et génère un script dans versions/. Vous appliquez ensuite avec alembic upgrade head. Relisez toujours le script généré avant de l'appliquer.

Comment appliquer ou annuler une migration Alembic ?

alembic upgrade head applique toutes les migrations jusqu'à la plus récente. alembic downgrade -1 annule la dernière, et alembic downgrade <revision> revient à une version précise. alembic history affiche la chaîne des révisions et alembic current la version appliquée sur la base.

Pourquoi utiliser render_as_batch avec SQLite dans Alembic ?

SQLite ne supporte quasiment pas ALTER TABLE. Le mode batch d'Alembic (render_as_batch=True dans env.py) contourne la limite en recréant la table puis en recopiant les données. Sans lui, les migrations qui modifient ou suppriment une colonne échouent sur SQLite.

Faut-il lancer alembic --autogenerate directement en production ?

Non. On génère et relit les migrations en développement, on les versionne dans Git, puis on applique seulement alembic upgrade head en production, après sauvegarde. Autogénérer contre la base de production risque de produire des changements destructeurs.

Pour aller plus loin

• PostgreSQL : passer de SQLite à une base de production robuste.

×

📖 Voir la documentation →