如何在FastAPI中进行数据库迁移操作_使用Python的Alembic工具-Python教程-PHP中文网

fastapi需借助alembic实现数据库迁移，关键在于正确加载模型与数据库url：需在env.py中显式导入base、配置target_metadata、动态读取settings中的database_url，并确保项目可安装以解决模块导入问题。

如何在fastapi中进行数据库迁移操作_使用python的alembic工具

FastAPI 本身不提供数据库迁移能力，必须借助外部工具；Alembic 是 SQLAlchemy 官方推荐的迁移方案，和 FastAPI 配合使用时，关键不是“能不能用”，而是“怎么让 alembic 正确加载你的 FastAPI 项目中的模型与数据库 URL”。

为什么 `alembic init` 后运行 `alembic revision --autogenerate` 找不到模型？

Alembic 默认只扫描 env.py 中导入的模块，而 FastAPI 项目通常把 Base 和模型分散在 models/ 或 db/models.py 下，不会自动被发现。

确保在 alembic/env.py 的 run_migrations_online() 或 run_migrations_offline() 之前，显式导入你的 Base 类（例如：from app.db.models import Base）
检查 target_metadata 是否指向正确的 Base.metadata，而不是空的 MetaData()
如果模型使用了 __table_args__ = {"schema": "public"} 等配置，--autogenerate 可能漏掉差异，建议先手动验证生成的 migration 文件

如何让 Alembic 读取 FastAPI 的实际数据库配置（比如从 `settings.py`）？

alembic.ini 是静态配置文件，不能直接执行 Python 逻辑，硬编码 URL 会导致开发/测试/生产环境混用，必须解耦。

Python 3.14.2

Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。

下载

在 alembic/env.py 开头动态加载配置：用 from app.core.config import settings（路径需确保可导入），再将 settings.DATABASE_URL 赋给 config.set_main_option("sqlalchemy.url", ...)
避免在 env.py 中直接调用 os.getenv——这会让配置来源不明确，且无法复用 FastAPI 的验证逻辑
若项目使用 Pydantic v2 的 BaseSettings，注意 alembic 运行时可能未触发 settings 实例化，需显式调用 settings = Settings()

运行 `alembic upgrade head` 报错 `ModuleNotFoundError: No module named 'app'`

这是 Python 模块路径问题，不是 Alembic 本身的问题。Alembic 启动时的当前工作目录和 Python 的 sys.path 决定了能否 import 你的包。

在项目根目录（含 pyproject.toml 或 setup.py）下执行 alembic upgrade head，而非 alembic/ 子目录内
确保项目已以可安装方式注册：运行 pip install -e .（对应 pyproject.toml 中有 [project] 配置）或 pip install -e ".[dev]"
临时调试可用 PYTHONPATH=$(pwd) alembic upgrade head（Linux/macOS），但不应作为长期方案

最常被忽略的一点：Alembic 的 revision 文件里自动生成的 upgrade() 函数默认使用 op.create_table()，但如果已有数据表，直接 upgrade 会报错重复创建。此时应删掉 migration 文件中建表语句，改用 op.execute("SELECT 1") 占位，或手动编辑为 op.create_table(..., if_not_exists=True)（仅部分方言支持）。