Alembic无法识别SQLModel模型，生成空迁移文件求助

问题背景 #

使用SQLModel结合Alembic做数据库迁移时，执行alembic revision --autogenerate生成的迁移文件中upgrade()和downgrade()仅包含pass语句，无法识别定义的User模型。

模型代码如下：

from sqlmodel import Field, SQLModel
from app.model.base_model import BaseModel
from enum import Enum  # 原代码缺失该导入，需补充

class UserType(Enum):
    buyer = "buyer"
    seller = "seller"

class User(BaseModel):
    user_id: int = Field(default=None, primary_key=True, index=True)
    role: UserType = Field(default="buyer")
    name: str = Field(default=None)
    email: str = Field(default=None)
    description: str = Field(default=None)
    password_hash: str = Field(default=None)
    profile_picture: str = Field(default=None)

env.py配置：

• 通过from app import model # noqa导入模型
• 设置target_metadata = SQLModel.metadata

排查与解决步骤 #

1. 确认BaseModel的继承关系 #

检查BaseModel必须直接或间接继承自SQLModel，否则User模型不会被注册到SQLModel.metadata中：

# app/model/base_model.py
from sqlmodel import SQLModel

class BaseModel(SQLModel):
    # 自定义公共字段
    pass

2. 确保模型被完整加载 #

• 检查app/model/__init__.py是否显式导入User模型，否则from app import model无法加载到目标模型：

  # app/model/__init__.py
  from .user import User
  from .base_model import BaseModel
  

• 也可以在env.py中直接导入具体模型，避免依赖__init__.py的导入逻辑：

  # env.py
  from app.model.user import User
  from sqlmodel import SQLModel
  target_metadata = SQLModel.metadata
  

3. 补全Enum字段的导入 #

原模型代码缺失from enum import Enum的导入，会导致代码运行报错，间接影响Alembic识别模型，必须补上该语句。

4. 验证target_metadata的正确性 #

确保env.py中target_metadata指向的是包含所有模型元数据的对象：

• 若BaseModel使用了自定义metadata，需调整为target_metadata = BaseModel.metadata
• 若使用默认的SQLModel.metadata，则需确保所有模型都继承自SQLModel或其子类

5. 清理残留迁移记录并重新生成 #

如果旧迁移记录有残留，可能导致自动生成失效：

1. 删除alembic/versions目录下的所有迁移文件
2. 删除数据库中的alembic_version表
3. 重新执行迁移命令：

   alembic revision --autogenerate -m "initial migration"
   alembic upgrade head
   

6. 检查版本兼容性 #

确保Alembic与SQLModel版本匹配，建议升级到最新稳定版：

pip install --upgrade sqlmodel alembic

内容的提问来源于stack exchange，提问作者DARK