Day 18 · 数据库迁移 Alembic

Week 3 · Day 18 / 56 · 返回大纲

一、为什么需要迁移

改了模型字段(比如加一个 priority 列),数据库不会自动更新。Alembic 负责生成和执行迁移脚本。

安装和初始化

uv add alembic

# 初始化
alembic init alembic

# 配置 alembic.ini
# sqlalchemy.url = sqlite:///todo.db

# 配置 alembic/env.py 的 target_metadata
# from models import Base
# target_metadata = Base.metadata

二、迁移命令

# 自动生成迁移脚本(对比模型和数据库差异)
alembic revision --autogenerate -m "add priority column"

# 执行迁移
alembic upgrade head

# 回退一个版本
alembic downgrade -1

# 查看历史
alembic history

# 查看当前版本
alembic current
⚠️ autogenerate 不是万能的: 它能检测加列/删表,但重命名列、改约束可能需要手写迁移脚本。

动手练习

练习 1:加字段
给 Todo 模型加 priority 字段
# models.py
class Todo(Base):
    priority: Mapped[str] = mapped_column(String(20), default="medium")

# 然后执行
# alembic revision --autogenerate -m "add priority"
# alembic upgrade head
查看答案
参考答案
# 每次改模型都要生成迁移
练习 2:回退
回退到上一个版本
alembic downgrade -1
# 检查数据库列是否回退了
查看答案
参考答案
# 开发时可以反复 upgrade/downgrade
练习 3:查看历史
查看所有迁移版本
alembic history --verbose
查看答案
参考答案
# 每个版本有一个 hash ID

打卡验收

理解数据库迁移的作用
会初始化 Alembic
会用 autogenerate 生成迁移
会执行 upgrade 和 downgrade
理解迁移版本管理
完成 3 个动手练习
能修改模型并生成迁移
知道什么时候需要手写迁移脚本
打卡方式: 全部勾选后,告诉我 "Day 18 打卡",并贴出你的代码。