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
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
| Étapes | Commande | Fonction | Équivalent Django |
|---|---|---|---|
| Initialiser | alembic init alembic | Créer l'environnement de migration (une seule fois) | — |
| Générer | alembic revision --autogenerate -m "description" | Détecter les changements de modèle, générer les scripts de migration | makemigrations |
| Execute | alembic upgrade head | Exécuter toutes les migrations non appliquées | migrate |
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
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ération | Django | Flask(Flask-Migrate) | FastAPI(Alembic) |
|---|---|---|---|
| Initialiser | Pas nécessaire | flask db init | alembic init alembic |
| Générer une migration | makemigrations | flask db migrate -m "description" | alembic revision --autogenerate -m "description" |
| Exécuter la migration | migrate | flask db upgrade | alembic upgrade head |
| Retour arrière | migrate app 0001 | flask db downgrade | alembic downgrade -1 |
| Degré d'automatisation | Maximale | Moyenne | Né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.
autres extensionsAperç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.