Alembic-Datenbankmigration
In diesem Kapitel lernst du, Alembic zu verwenden, um Änderungen am Datenbankschema zu verwalten, und die Gemeinsamkeiten und Unterschiede zu Django Migration und Flask-Migrate zu verstehen.
Warum brauchen wir Migrationswerkzeuge?
Base.metadata.create_all()Hat außerdem einen fatalen Fehler: Erstellt nur, wenn die Tabelle nicht existiert, und das Ändern einer bestehenden Tabellenstruktur wird nicht automatisch synchronisiert.
AlembicEs ist das offizielle Migrationstool von SQLAlchemy, und Djangosmakemigrations/migrateund Flasks Flask-Migrate orientieren sich alle auf der zugrunde liegenden Ebene an Alembics Design.
Installation und Initialisierung
(venv) $ pip install alembic (venv) $ alembic init alembic Creating directory alembic/... done
Generierte Verzeichnisstruktur:
alembic/ ├── versions/ # 迁移脚本存放目录 ├── env.py # 迁移环境配置（需手动修改！） └── script.py.mako # 迁移脚本模板 alembic.ini # Alembic 配置文件
Konfiguriere env.py, um eine Verbindung zu deinen Modellen herzustellen
Dies ist ein entscheidender Schritt – Alembic weiß standardmäßig nicht, wo deine SQLAlchemy-Modelle sind.
Beispiel
import sys
from pathlib import Path
# Projektstammverzeichnis zu sys.path hinzufügen (um sicherzustellen, dass du deine eigenen Module importieren kannst)
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from database import Base, engine
from models import Category, Post # Alle Modelle importieren, um sicherzustellen, dass Base.metadata sie enthält.
# target_metadata muss auf die Modell-Metadaten gesetzt werden
target_metadata = Base.metadata
Gleichzeitig ändernalembic.iniDatenbankverbindung in:
# 文件路径：alembic.ini sqlalchemy.url = sqlite:///./blog.db
Migration in drei Schritten
| Schritte | Befehl | Funktion | Django-Äquivalent |
|---|---|---|---|
| Initialisieren | alembic init alembic | Migrationsumgebung erstellen (nur einmalig) | — |
| Generieren | alembic revision --autogenerate -m "description" | Modelländerungen erkennen, Migrationsskripte generieren | makemigrations |
| Execute | alembic upgrade head | Alle nicht angewendeten Migrationen ausführen | migrate |
Migrationen generieren und ausführen
(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, 初始化
Praxis: Das Feld read_count hinzufügen
Beispiel
class Post(Base):
# ... vorhandene Felder ...
read_count = Column(Integer, default=0) # Lesezähler
(venv) $ alembic revision --autogenerate -m "Post 新增 read_count 字段" (venv) $ alembic upgrade head
Rollback
(venv) $ alembic downgrade -1 # 回退到上一个版本
alembic upgrade headinheadGibt die neueste Version an. Sie können auch eine bestimmte Versionsnummer angeben:alembic upgrade xxxx(Versions-ID).
Vergleich der Migrationstools in drei Frameworks
| Aktion | Django | Flask（Flask-Migrate） | FastAPI（Alembic） |
|---|---|---|---|
| Initialisieren | Nicht nötig | flask db init | alembic init alembic |
| Migration generieren | makemigrations | flask db migrate -m "description" | alembic revision --autogenerate -m "description" |
| Migration ausführen | migrate | flask db upgrade | alembic upgrade head |
| Rollback | migrate app 0001 | flask db downgrade | alembic downgrade -1 |
| Grad der Automatisierung | Höchste | Mittel | Erfordert manuelle Konfiguration von env.py |
Kapitelzusammenfassung
In diesem Kapitel hast du den vollständigen Alembic-Workflow gemeistert: alembic init Initialisierung, Konfiguration von env.py zum Verbinden von Modellen, revision --autogenerate zum Generieren von Migrationen, upgrade head zum Ausführen und downgrade zum Zurückrollen.
Alembic erfordert mehr Konfigurationsschritte als die Migrationstools von Django/Flask, aber es ist auf einer niedrigeren Ebene angesiedelt und flexibler.
Weitere ErweiterungenVorschau auf das nächste Kapitel: Wenn mehr Artikel vorhanden sind, werden Suche und Paginierung benötigt. Das nächste Kapitel implementiert die kombinierte Stichwortsuche und Paginierung basierend auf offset/limit.