SQLAlchemy设置onupdate='CASCADE'时更新意外修改未指定列报错

算力阿峰

2026-9-2

问题根因

核心原因是onupdate参数配置位置错误，属于SQLAlchemy API的误用：

Column构造方法接收的onupdate参数是ORM层面的更新自动赋值配置：只要某条记录触发UPDATE操作，ORM就会自动把该参数指定的值/可调用对象的返回值赋给对应字段，最常见的用法是更新时间字段配置onupdate=datetime.datetime.utcnow，实现更新时自动写入当前时间。这个参数和数据库外键的ON UPDATE级联规则完全无关。
你把字符串'CASCADE'传给了user_id列的Column.onupdate参数，导致每次更新Project记录时，ORM都会自动尝试给user_id赋值为字符串'CASCADE'。由于user_id是UUID/GUID类型，ORM尝试将'CASCADE'解析为UUID时，发现它不是合法的十六进制UUID字符串，就抛出了badly formed hexadecimal UUID string错误。
你原本想要配置的数据库外键ON UPDATE CASCADE约束，参数需要写在ForeignKey构造函数内部，而非Column的参数列表中，属于参数传错位置导致的异常。

这也完全对应你观察到的现象：没有手动修改user_id字段，生成的UPDATE语句却自动带上了user_id的赋值逻辑。

修复方案

调整user_id字段的配置，将onupdate='CASCADE'从Column参数移动到ForeignKey参数内，写法对比如下：

# 错误原写法
user_id= Column(GUID, ForeignKey('users.id'), onupdate='CASCADE')

# 修正后正确写法
user_id= Column(GUID, ForeignKey('users.id', onupdate='CASCADE'))

（可选优化）当前的异步会话写法没有覆盖异常场景的资源回收，容易出现数据库连接泄漏，建议使用上下文管理器自动管理会话生命周期，无需手动调用close()：

@router.put('/{id}/update-status')
async def update_project_status(id: UUID, status: int , user = Depends(current_active_user)):
    try:
        async with async_session_maker() as session:
            query = select(Project).where(Project.id == id)
            project = (await session.scalars(query)).one()
            project.project_status_id = status
            await session.commit()
    except Exception as error:
        print(error)
        return repr(error)

如果是使用Alembic做数据库迁移，修正模型配置后需要生成新的迁移脚本并执行，同步数据库层面的外键约束规则，确保配置生效。

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