fastapi: Alembic和flask db 的对应关系

一， Alembic和flask db的关系

FastAPI 本身并没有默认的数据库迁移库，因为它是一个微框架（Microframework），不绑定任何特定的 ORM 或数据库工具。
但在实际开发中，FastAPI 社区官方推荐且最广泛使用的数据库迁移库是 Alembic。

它与 flask db（即 Flask-Migrate 扩展）有着非常紧密的对应关系，因为它们的底层完全是同一个东西。

Flask-Migrate 的本质是一个包装器（Wrapper），它把 Alembic 包装成了 Flask 的命令行插件（即 flask db ...）。
而在 FastAPI 中，你不需要这个外壳，而是直接使用 Alembic 的原生命令行工具（即 alembic ...）。

 

区别：

• 没有全局 app 绑定：在 Flask 中，Flask-Migrate 会自动从 Flask 配置中读取数据库连接串（SQLALCHEMY_DATABASE_URI）。
  而在 FastAPI 中，你需要手动修改 Alembic 生成的 alembic.ini 文件，或者在 env.py 中将 sqlalchemy.url 指向你的 FastAPI 数据库配置。
• 模型导入：为了让 alembic 能够自动检测到模型的变换（--autogenerate），你必须在 alembic/env.py 文件中，
  将你的 Base 模型的 metadata 赋值给 target_metadata
  （例如：target_metadata = Base.metadata），并确保所有模型类都在该文件中被 import 引入。

 

二，两者的对应

操作目的	Flask-Migrate 命令 (flask db)	FastAPI / Alembic 原生命令 (alembic)
初始化迁移环境	flask db init	alembic init alembic
自动生成迁移脚本	flask db migrate -m "注脚"	alembic revision --autogenerate -m "注脚"
执行升级（应用迁移）	flask db upgrade	alembic upgrade head
执行降级（回滚迁移）	flask db downgrade	alembic downgrade -1
查看当前数据库版本	flask db current	alembic current

三，flask db stamp head 对应的原生 Alembic 命令

flask db stamp head 对应的原生 Alembic 命令是：

alembic stamp head

作用：它不会修改你数据库中的任何表结构，而只是把数据库中的 alembic_version 表的版本号（Version Num）直接修改为当前最新的迁移版本（head）

使用场景：当你手动在数据库里建了表，或者用 Base.metadata.create_all(engine) 进行了初始化，导致数据库结构已经是最新的，但 alembic_version 表为空（或版本落后）。
                      此时运行 stamp head 可以告诉 Alembic：“数据库已经是最新状态了，标记一下即可，不用再执行升级脚本”。