Alembic 数据库迁移
本章你将学会用 Alembic 管理数据库结构变更，理解与 Django Migration、Flask-Migrate 的异同。
为什么需要迁移工具？
Base.metadata.create_all() 同样有致命缺陷：只在表不存在时创建，修改已有表结构不会自动同步。
Alembic 是 SQLAlchemy 官方的迁移工具，Django 的 makemigrations/migrate 和 Flask 的 Flask-Migrate，底层都是借鉴了 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 模型在哪里。
实例
# 文件路径：alembic/env.py（修改关键部分）
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
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 "描述" | 检测模型变化，生成迁移脚本 | makemigrations |
| 执行 | 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 字段
实例
# 文件路径：models.py 的 Post 类中新增
class Post(Base):
# ... 已有字段 ...
read_count = Column(Integer, default=0) # 阅读次数
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 head中的head表示最新版本。也可以指定具体版本号：alembic upgrade xxxx（版本 ID）。
三框架迁移工具对照
| 操作 | Django | Flask（Flask-Migrate） | FastAPI（Alembic） |
|---|---|---|---|
| 初始化 | 无需 | flask db init | alembic init alembic |
| 生成迁移 | makemigrations | flask db migrate -m "描述" | alembic revision --autogenerate -m "描述" |
| 执行迁移 | 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 的分页功能。