Migration de base de données Alembic

Dans ce chapitre, vous apprendrez à utiliser Alembic pour gérer les modifications du schéma de base de données et à comprendre les similitudes et différences avec Django Migration et Flask-Migrate.


Pourquoi avons-nous besoin d'outils de migration ?

Base.metadata.create_all()Il présente également un défaut fatal : il ne crée que lorsque la table n'existe pas, et la modification d'une structure de table existante ne sera pas synchronisée automatiquement.

AlembicC'est l'outil de migration officiel de SQLAlchemy, et celui de Djangomakemigrations/migrateet Flask-Migrate de Flask s'inspirent tous du design d'Alembic au niveau sous-jacent.


Installation et initialisation

(venv) $ pip install alembic
(venv) $ alembic init alembic
Creating directory alembic/... done

Structure de répertoires générée :

alembic/
├── versions/          # 迁移脚本存放目录
├── env.py             # 迁移环境配置(需手动修改!)
└── script.py.mako     # 迁移脚本模板
alembic.ini            # Alembic 配置文件

Configurer env.py pour se connecter à vos modèles

Il s'agit d'une étape clé—Alembic ne sait pas où se trouvent vos modèles SQLAlchemy par défaut.

Exemple

# Chemin du fichier : alembic/env.py (modifier les parties clés)
import sys
from pathlib import Path

# Ajouter le répertoire racine du projet à sys.path (pour garantir que vous pouvez importer vos propres modules)
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from database import Base, engine
from models import Category, Post   # Importer tous les modèles pour garantir que Base.metadata les inclut.

# target_metadata doit être défini sur les métadonnées du modèle
target_metadata = Base.metadata

Modifier simultanémentalembic.iniConnexion à la base de données dans :

# 文件路径:alembic.ini
sqlalchemy.url = sqlite:///./blog.db

Migration en trois étapes

ÉtapesCommandeFonctionÉquivalent Django
Initialiseralembic init alembicCréer l'environnement de migration (une seule fois)—
Généreralembic revision --autogenerate -m "description"Détecter les changements de modèle, générer les scripts de migrationmakemigrations
Executealembic upgrade headExécuter toutes les migrations non appliquéesmigrate

Générer et exécuter les migrations

(venv) $ alembic revision --autogenerate -m "初始化 Post 和 Category 模型"
INFO  [alembic.autogenerate] Detected added table 'categories'
INFO  [alembic.autogenerate] Detected added table 'posts'
Generating alembic/versions/xxxx_initial.py ... done

(venv) $ alembic upgrade head
INFO  [alembic.runtime.migration] Running upgrade -> xxxx, 初始化

Pratique : ajouter le champ read_count

Exemple

# Chemin du fichier : ajouté dans la classe Post de models.py
class Post(Base):
    # ... champs existants ...
    read_count = Column(Integer, default=0)   # Nombre de lectures
(venv) $ alembic revision --autogenerate -m "Post 新增 read_count 字段"
(venv) $ alembic upgrade head

Retour arrière

(venv) $ alembic downgrade -1        # 回退到上一个版本

alembic upgrade headinheadIndique la version la plus récente. Vous pouvez également préciser un numéro de version spécifique :alembic upgrade xxxx(ID de version).


Comparaison des outils de migration entre trois frameworks

OpérationDjangoFlask(Flask-Migrate)FastAPI(Alembic)
InitialiserPas nécessaireflask db initalembic init alembic
Générer une migrationmakemigrationsflask db migrate -m "description"alembic revision --autogenerate -m "description"
Exécuter la migrationmigrateflask db upgradealembic upgrade head
Retour arrièremigrate app 0001flask db downgradealembic downgrade -1
Degré d'automatisationMaximaleMoyenneNécessite une configuration manuelle d'env.py

Résumé du chapitre

Dans ce chapitre, vous avez maîtrisé le flux de travail complet d'Alembic : l'initialisation avec alembic init, la configuration de env.py pour connecter les modèles, revision --autogenerate pour générer les migrations, upgrade head pour exécuter, et downgrade pour revenir en arrière.

Alembic nécessite plus d'étapes de configuration que les outils de migration Django/Flask, mais il est plus bas niveau et plus flexible.

Aperçu du prochain chapitre : avec plus d'articles, la recherche et la pagination sont nécessaires. Le prochain chapitre met en œuvre la recherche conjointe par mots-clés et la pagination basée sur offset/limit.

autres extensions