如何让SQLAlchemy使用枚举值而非名称？解决查询报错问题

问题根源 #

你定义的ReportStatus枚举成员绑定了字符串值，但SQLAlchemy默认会把枚举的成员名称（比如DONE）作为数据库存储值。当你用枚举的实际值（比如'done'）查询时，数据库找不到匹配项，因此抛出"'done' is not among the defined enum values"的错误。

解决方案 #

1. 正确定义Python枚举类 #

先确保你的枚举类正确绑定目标字符串值：

from enum import Enum

class ReportStatus(Enum):
    PENDING = 'pending'
    PROCESSING = 'processing'
    DONE = 'done'
    ERROR = 'error'

2. 配置SQLAlchemy字段使用枚举值 #

通过values_callable参数，让SQLAlchemy将枚举的实际值而非成员名称存入数据库：

from sqlalchemy import Column, Integer, Enum as SqlEnum
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class Report(Base):
    __tablename__ = 'reports'
    id = Column(Integer, primary_key=True)
    # 指定values_callable提取枚举值作为数据库存储项
    status = Column(
        SqlEnum(
            ReportStatus,
            values_callable=lambda enum_cls: [item.value for item in enum_cls]
        )
    )

3. 更新数据库结构 #

修改字段配置后，需要同步数据库表结构：

• 若使用Alembic迁移工具，生成并执行迁移脚本，确保数据库中的枚举（或字符串）字段可选值更新为'pending'、'processing'、'done'、'error'
• 若直接操作数据库，手动修改对应字段的枚举约束或字符串校验规则

4. 查询的正确用法 #

配置完成后，两种查询方式都能正常工作：

# 直接用枚举值查询
done_reports = session.query(Report).filter(Report.status == 'done').all()

# 用枚举成员查询（同样兼容）
done_reports = session.query(Report).filter(Report.status == ReportStatus.DONE).all()

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