如何在FastAPI+PostgreSQL中将枚举值以整数形式存入数据库？

一、字符串存储枚举的合理性分析 #

你判断的「存整数更优」是准确的，先明确两种存储方式的优缺点：

• 字符串存储：
  • 优势：可读性极强，直接查看数据库就能知道权限类型，无需对照枚举定义；若后续仅修改枚举名称（不改动value），数据库数据无需更新。
  • 劣势：存储占用大于整数（比如"Admin"占5字节，整数仅需4字节或更小）；大数据量下字符串查询对比的性能不如整数；若需修改枚举名称，需批量更新数据库中所有对应记录，成本较高。
• 整数存储：
  • 优势：存储效率高、查询性能好；枚举名称修改不影响数据库数据（只要value不变）；更符合权限这类固定业务标识的存储习惯。
  • 劣势：可读性差，需对照枚举定义才能知道数值对应的权限。

对于权限管理系统，整数存储显然更适合，因为权限的数值一般不会轻易变更，而性能和维护成本更关键。

二、为什么直接用Permission.Admin.value赋值失败？ #

你之前的模型中permission字段用的是Enum(Permission)类型，SQLAlchemy会默认将枚举的**名称（name）**存入数据库，并且要求赋值时传入Permission枚举的实例，而非整数。直接传Permission.Admin.value（整数）会因类型不匹配而失败。

三、实现整数存储枚举的两种方案 #

方案1：使用Integer字段+混合属性（hybrid_property） #

直接将数据库字段定义为Integer，通过混合属性在代码层面做枚举与整数的转换，兼顾数据库的整数存储和代码的枚举可读性：

# model.py
from sqlalchemy.ext.hybrid import hybrid_property
from enum import IntEnum

class Permission(IntEnum):
    Admin = 0
    Edit = 1
    Viewer = 2

class User(BaseModel):
    __tablename__ = "users"

    username = Column(String, primary_key=True, index=True)
    password = Column(String)
    # 数据库中实际存储整数的字段，命名为_permission，对外暴露permission属性
    _permission = Column(Integer, name="permission")

    @hybrid_property
    def permission(self):
        # 读取时将整数转为枚举实例
        return Permission(self._permission)

    @permission.setter
    def permission(self, value):
        # 赋值时处理枚举实例或整数
        if isinstance(value, Permission):
            self._permission = value.value
        elif isinstance(value, int):
            # 验证整数是否为合法的枚举值
            if value not in [p.value for p in Permission]:
                raise ValueError(f"无效的权限值：{value}")
            self._permission = value
        else:
            raise TypeError(f"权限值必须是Permission枚举或整数，当前类型：{type(value)}")

使用方式：

# 赋值枚举实例
user = User(username="test", password="123", permission=Permission.Admin)
# 或直接赋值合法整数
user.permission = 1  # 对应Permission.Edit

方案2：自定义SQLAlchemy类型（推荐） #

通过继承TypeDecorator实现自定义类型，让SQLAlchemy自动处理枚举与整数的转换，代码更简洁：

# 自定义类型
from sqlalchemy import TypeDecorator, Integer

class IntEnumType(TypeDecorator):
    impl = Integer
    cache_ok = True

    def __init__(self, enum_type):
        self.enum_type = enum_type
        super().__init__()

    def process_bind_param(self, value, dialect):
        # 写入数据库前，将枚举转为整数
        if value is None:
            return None
        if isinstance(value, self.enum_type):
            return value.value
        elif isinstance(value, int):
            if value not in [item.value for item in self.enum_type]:
                raise ValueError(f"枚举{self.enum_type.__name__}不支持值：{value}")
            return value
        raise TypeError(f"期望类型为{self.enum_type.__name__}或int，实际为{type(value)}")

    def process_result_value(self, value, dialect):
        # 从数据库读取后，将整数转为枚举实例
        if value is None:
            return None
        return self.enum_type(value)

修改User模型：

class User(BaseModel):
    __tablename__ = "users"

    username = Column(String, primary_key=True, index=True)
    password = Column(String)
    # 使用自定义类型
    permission = Column(IntEnumType(Permission))

使用方式：

user = User(username="test", password="123", permission=Permission.Viewer)
# 或直接赋值合法整数
user.permission = 0

四、迁移脚本处理 #

因为之前已经用Alembic生成了基于Enum类型的迁移脚本，现在需要修改迁移脚本，将permission字段的类型从枚举改为整数：

1. 自动生成新的迁移脚本：

alembic revision --autogenerate -m "change permission field to integer"

2. 检查生成的迁移脚本，确保alter table users alter column permission type integer这类语句正确（可能需要手动调整，避免数据丢失）。
3. 执行迁移：

alembic upgrade head

注意：如果数据库中已有数据，需要先将原字符串枚举值映射为对应的整数，再修改字段类型，比如先运行更新语句：

UPDATE users SET permission = 
    CASE permission
        WHEN 'Admin' THEN 0
        WHEN 'Edit' THEN 1
        WHEN 'Viewer' THEN 2
    END;

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