Alembic无法检测SQLModel中新增的唯一约束问题求助

1. 基类中businessKey的unique=True未被识别 #

问题根源：你的BusinessKeyModel继承自PydanticBase而非SQLModel，Field参数里的unique=True只是Pydantic的数据验证规则，不会同步到SQLAlchemy的数据库schema定义中，因此Alembic无法检测到该约束。

可行解决方案：

• 方案一：将BusinessKeyModel改为继承SQLModel（如果不需要单独作为纯Pydantic模型使用）：

class BusinessKeyModel(SQLModel):  # 替换原PydanticBase
    businessKey: Optional[str] = Field(
        alias="businessKey",
        max_length=255,
        description=DescriptionConstants.BUSINESS_KEY,
        nullable=True,
        unique=True
    )

• 方案二：若必须保留PydanticBase继承，在SQLModel子类中重新定义businessKey并通过sa_column指定SQL层面的唯一约束：

class BaseTableModel(SQLModel, BusinessKeyModel):
    businessKey: Optional[str] = Field(
        alias="businessKey",
        max_length=255,
        nullable=True,
        sa_column=Column(String(255), nullable=True, unique=True)
    )

2. UserRoleMapping的联合唯一约束未被识别 #

针对这个问题，逐一排查以下可能：

• 未显式导入SQLAlchemy的UniqueConstraint：虽然SQLModel会自动关联，但显式导入可避免潜在的命名空间问题：

  from sqlalchemy import UniqueConstraint
  
  class UserRoleMapping(UserRoleMappingBase, table=True):
      __table_args__ = (
          UniqueConstraint("userId", "roleId"),
          {"schema": "dbx_v2"}
      )
  

• Alembic未加载目标模型：检查alembic/env.py，确保target_metadata包含了UserRoleMapping所在模块的所有模型，或者直接显式导入该模型：

  # 在env.py的合适位置添加
  from your_project.models import UserRoleMapping  # 替换为实际模块路径
  

• Alembic缓存旧模型结构：如果之前生成过迁移文件，可能缓存了旧的模型定义。删除alembic/versions下未应用的旧迁移文件，重新执行生成命令：

  alembic revision --autogenerate -m "add user-role unique constraint"
  

• __table_args__格式错误：确保__table_args__是一个元组，其中第一个元素为UniqueConstraint实例，第二个为包含schema的字典，避免嵌套或语法错误。

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