Alembic——一个专门用来给数据库“做版本管理”和“持续装修”的工具

自动化：能自动检测模型的变化，帮你生成包含 ALTER TABLE 等命令的迁移脚本。
可回滚：每个变更都像Git的commit一样，万一出错了，可以一键回退到之前的状态
协作友好：所有变更都有脚本记录，便于团队协作和生产环境部署

下面我手把手教你，如何把项目从 create_all 模式平滑迁移到 Alembic。

⚙️Step 1：在你的项目中安装并初始化Alembic

安装Alembic
在终端里激活你的虚拟环境，然后执行：

pip install alembic

初始化迁移环境
在你的项目根目录（也就是你存放 alembic.ini 配置文件的地方）下，运行：

alembic init -t async migrations

注意：如果你用的是传统的同步SQLAlchemy，可以不加 -t async 这个参数。
这条命令会帮你创建一个叫 migrations 的文件夹（所有迁移脚本都存在这里面）和一个 alembic.ini 的配置文件

🧩 Step 2：连接你的模型 (最关键的一步)

Alembic得知道你的模型长什么样，才能知道“变化”是什么

填写数据库连接URL
用任何文本编辑器打开根目录下的 alembic.ini 文件，找到 sqlalchemy.url 这一行，改成你自己的数据库连接字符串

# 示例
sqlalchemy.url = sqlite+aiosqlite:///./your_app.db

导入你的模型元数据
打开 migrations/env.py 文件，这是Alembic的核心配置文件。你需要把 target_metadata = None 修改成你的 Base.metadata 对象，这样Alembic才能“看到”你定义的模型

# migrations/env.py

import sys
from pathlib import Path

# 将项目的根目录加入Python路径，确保能导入你的模块
sys.path.append(str(Path(__file__).parent.parent))

from yourapp.database import Base  # 请根据你的实际路径修改，确保能导入Base对象。
from alembic import context

# 这里是关键：将你的Base的metadata赋值给target_metadata
target_metadata = Base.metadata

# ... 文件其余部分保持不变

特别提醒：务必将 yourapp.database 替换为你自己项目中 Base 定义所在的真实路径。

🪄 Step 3：生成并应用迁移 (告别 create_all)

现在Alembic已经连接上你的模型和数据库了，可以开始发挥它的神力了。
1.创建你的第一个迁移脚本（生成基线）
在终端执行：

alembic revision --autogenerate -m "initial tables"

这条命令会让你看到魔法上演的时刻：Alembic会去 migrations/versions 文件夹下生成一个新的Python文件，比如 xxxxxxxxxxxx_initial_tables.py。打开它，你会发现里面已经根据你当前的模型和数据库表结构的差异，自动写好了 upgrade() (升级) 和 downgrade() (降级) 函数，里面是各种 op.create_table() 和 op.add_column() 操作。

正式应用到数据库

alembic upgrade head

head 代表最新的版本。执行后，Alembic会执行刚刚生成的迁移脚本，把你的数据库更新到最新的模型状态。同时，它还会在你的数据库里自动创建一个名为 alembic_version 的表，专门用来记录当前数据库是哪个版本。

🔄 Step 4：后续的迭代流程

以后每当你的模型（比如 User 表）发生变更（新增字段、修改类型等），就不再需要 create_all 了，只需要重复下面两步即可：
1.自动生成新的迁移脚本

alembic revision --autogenerate -m "add user email field"

记得要复查一下自动生成的脚本，特别是涉及数据迁移的复杂操作时，确保它符合你的预期
2.应用变更

alembic upgrade head

🧰常用命令速查

alembic upgrade head：升级到最新版本。
alembic downgrade -1：回退到上一个版本。
alembic history：查看所有的迁移版本历史。
alembic current：查看当前数据库处于哪个版本。

💡 总结一下

create_all：就像相机拍立得，只能记录最初的瞬间。适合项目刚开始、快速搭建原型的时候用。
Alembic：就像拍电影，有完整的剧本（迁移脚本）、可以随时重拍（回滚）、每次修改都留下记录。它是管理生产环境、团队协作的正式流程，能让你彻底告别“模型改了，表却忘加列”的尴尬

一开始配置虽然稍微有点小步骤，但配置好之后，整个流程会非常顺畅，绝对是“一劳永逸”的好工具～

Alembic——一个专门用来给数据库“做版本管理”和“持续装修”的工具