FastAPI的Alembic踩坑记录：缺失历史迁移脚本如何保留数据重建版本控制

问题背景

在基于 FastAPI + SQLModel（或 SQLAlchemy）的 Web 开发中，为了方便测试或复用已有数据，开发者常常会直接将包含历史数据的 SQLite 数据库文件（如 company.db）拷贝到新的项目目录中，以省去重新录入数据的麻烦。

然而，当在新的项目中新增了数据模型，并尝试运行 Alembic 生成新的迁移脚本时，通常会遭遇如下报错：

text 复制代码

ERROR [alembic.util.messaging] Can't locate revision identified by '96fa5af915e6'
FAILED: Can't locate revision identified by '96fa5af915e6'

原因分析

导致该错误的原因在于 Alembic 的版本控制机制。

直接拷贝的数据库文件中，不仅包含了业务数据表，还包含了一个名为 alembic_version 的系统表。这张表里记录了该数据库当前处于哪个迁移版本（例如上述报错中的 96fa5af915e6）。

但在新的项目目录中，alembic/versions/ 文件夹下往往是空的，或者缺少对应的历史 .py 迁移脚本。Alembic 在比对数据库版本号与本地脚本时找不到对应的文件，导致版本链条断裂，从而触发报错。

解决思路：重置状态并"盖戳（Stamp）"

核心思路是：清除数据库内的旧版本记录，让 Alembic 针对"旧模型"生成一个初始建表脚本，然后利用 stamp head 命令告诉 Alembic"假装这个初始脚本已经执行过了"，最后再引入"新模型"生成实际的变更脚本。

具体操作步骤

第一步：清除数据库中的旧版本记录

首先，需要删除 SQLite 数据库中的 alembic_version 表，让数据库在 Alembic 面前变成一张"白纸"。

可以在项目根目录临时新建一个 Python 脚本（如 fix_db.py）来执行清理：

python 复制代码

# fix_db.py
import sqlite3

# 连接到拷贝过来的数据库
conn = sqlite3.connect("company.db")
cursor = conn.cursor()

# 删除 Alembic 版本记录表
cursor.execute("DROP TABLE IF EXISTS alembic_version;")
conn.commit()
conn.close()

print("已成功清除旧版本记录")

运行该脚本后，即可将其删除。

第二步：暂时隐藏新数据模型

打开项目中的 alembic/env.py 文件。此时，暂且注释掉本次开发中刚刚新增的数据模型，仅保留数据库中已经存在的旧模型。

python 复制代码

# alembic/env.py 顶部导入区域

# 暂时注释掉新模型，避免被 Alembic 扫到
# from models import product, product_category  

# 仅保留拷贝数据库时已经存在的旧模型
from models import company, news

第三步：生成基准脚本并"盖戳"

在终端中依次执行以下两条命令。

生成基准脚本：让 Alembic 根据当前放开的旧模型，生成一个全量的建表脚本。

bash 复制代码

alembic revision --autogenerate -m "init old tables"

打上版本戳（关键） ：执行 stamp head 命令。该命令会将数据库的版本号直接更新为刚才生成的基准脚本的版本号，但不会真正去执行脚本中的建表 SQL。这完美避免了表已存在导致的冲突，同时重新建立起了完整的版本链。

bash 复制代码

alembic stamp head

第四步：恢复新模型并生成实际迁移

完成基准对齐后，就可以处理真正的新增需求了。

回到 alembic/env.py，取消第二步中的注释，让 Alembic 能够识别到新模型：

python 复制代码

# alembic/env.py 顶部导入区域

from models import product, product_category  # 取消注释
from models import company, news

最后，正常执行标准的迁移生成与应用命令：

bash 复制代码

# 生成包含新增表或字段的实际迁移脚本
alembic revision --autogenerate -m "Create new tables"

# 将变更应用到数据库
alembic upgrade head

至此，新的数据表会被成功创建，原有的历史业务数据也完好无损地保留了下来，Alembic 的版本控制恢复正常运转。

总结

在进行数据库文件的物理迁移时，务必注意 alembic_version 表与本地脚本文件的同步问题。善用 alembic stamp 命令，可以在不丢失数据的前提下，灵活修复版本链断裂的异常，是处理 ORM 迁移痛点的一项重要技巧。