Миграция базы данных Alembic
В этой главе вы научитесь использовать Alembic для управления изменениями схемы базы данных и поймёте сходства и различия с Django Migration и Flask-Migrate.
Зачем нужны инструменты миграции?
Base.metadata.create_all()Также имеет фатальный недостаток: создаёт только при отсутствии таблицы, а изменение структуры существующей таблицы не будет автоматически синхронизироваться.
AlembicЭто официальный инструмент миграции SQLAlchemy, а Djangomakemigrations/migrateи Flask-Migrate от Flask заимствуют дизайн Alembic на низком уровне.
Установка и инициализация
(venv) $ pip install alembic (venv) $ alembic init alembic Creating directory alembic/... done
Сгенерированная структура каталогов:
alembic/ ├── versions/ # 迁移脚本存放目录 ├── env.py # 迁移环境配置（需手动修改！） └── script.py.mako # 迁移脚本模板 alembic.ini # Alembic 配置文件
Настройте env.py для подключения к вашим моделям
Это ключевой шаг — Alembic по умолчанию не знает, где находятся ваши модели SQLAlchemy.
Пример
import sys
from pathlib import Path
# Добавьте корневой каталог проекта в sys.path (чтобы вы могли импортировать собственные модули)
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from database import Base, engine
from models import Category, Post # Импортируйте все модели, чтобы гарантировать, что Base.metadata включает их.
# target_metadata должен быть установлен в метаданные модели
target_metadata = Base.metadata
Измените одновременноalembic.iniПодключение к базе данных в:
# 文件路径：alembic.ini sqlalchemy.url = sqlite:///./blog.db
Миграция в три шага
| Шаги | Команда | Функция | Эквивалент в Django |
|---|---|---|---|
| Инициализация | alembic init alembic | Создайте среду миграций (только один раз) | — |
| Сгенерировать | alembic revision --autogenerate -m "description" | Обнаружить изменения модели, сгенерировать скрипты миграций | makemigrations |
| Execute | alembic upgrade head | Выполнить все неприменённые миграции | migrate |
Сгенерировать и выполнить миграции
(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, 初始化
Практика: добавить поле read_count
Пример
class Post(Base):
# ... существующие поля
read_count = Column(Integer, default=0) # Количество чтений
(venv) $ alembic revision --autogenerate -m "Post 新增 read_count 字段" (venv) $ alembic upgrade head
Откат
(venv) $ alembic downgrade -1 # 回退到上一个版本
alembic upgrade headinheadУказывает последнюю версию. Вы также можете указать конкретный номер версии:alembic upgrade xxxx(ID версии).
Сравнение инструментов миграции в трёх фреймворках
| Действие | Django | Flask（Flask-Migrate） | FastAPI（Alembic） |
|---|---|---|---|
| Инициализация | Не требуется | flask db init | alembic init alembic |
| Сгенерировать миграцию | makemigrations | flask db migrate -m "description" | alembic revision --autogenerate -m "description" |
| Выполнить миграцию | migrate | flask db upgrade | alembic upgrade head |
| Откат | migrate app 0001 | flask db downgrade | alembic downgrade -1 |
| Степень автоматизации | Наивысшая | Средняя | Требуется ручная настройка env.py |
Итоги главы
В этой главе вы освоили полный рабочий процесс Alembic: инициализацию с помощью alembic init, настройку env.py для подключения моделей, revision --autogenerate для создания миграций, upgrade head для выполнения и downgrade для отката.
Alembic требует больше шагов настройки, чем инструменты миграции Django/Flask, но он более низкоуровневый и гибкий.
Другие расширенияПредпросмотр следующей главы: при увеличении количества статей требуются поиск и пагинация. В следующей главе реализуются комбинированный поиск по ключевым словам и пагинация на основе offset/limit.