执行简单更新语句时遇到SqlAlchemy StaleDataError的排查求助

问题重现 #

你的代码执行后抛出StaleDataError：

user = session.query(User).get(1)
user.first_name # John
user.first_name = 'Sally'
session.commit()

# > sqlalchemy.orm.exc.StaleDataError: UPDATE statement on table 'user' expected to update 1 row(s);
#   -1 were matched.

根据SQLAlchemy文档，该错误的触发场景包括：

操作遇到了无法解释的数据库状态。
导致此问题的情况包括：
刷新操作尝试更新或删除行时，UPDATE或DELETE语句匹配到的行数超出预期。注意，当使用version_id_col时，UPDATE或DELETE语句还会匹配当前已知的版本标识符。
带有version_id_col的映射对象被刷新后，数据库返回的版本号与对象自身的版本号不匹配。
一个对象与其父对象分离，但该对象之前附加到另一个已被垃圾回收的父对象，无法确定新父对象是否为最新的“父对象”。

关于version_id_col的疑问 #

什么是version_id_col？ #

这是SQLAlchemy的乐观锁实现机制：它会在数据表中维护一个版本列（比如version、row_version），每次更新行时该列自动递增。当你更新对象时，SQLAlchemy会生成包含当前版本号的UPDATE语句，只有版本号和ID都匹配的行才会被更新——如果版本号不匹配，说明该行已经被其他会话修改，直接抛出StaleDataError避免并发冲突。

如何确认是否启用了version_id_col？ #

• 查看你的User模型定义：如果有类似version = Column(Integer, default=1, nullable=False)的字段，并且在模型里配置了__mapper_args__ = {'version_id_col': version}，或者用了@versioned装饰器，就说明开启了乐观锁。
• 直接查数据库的user表，看是否存在一个每次更新都会自动递增的整数列（通常命名为version、row_version）。

为什么会出现“找不到刚查询到的行ID”？ #

错误提示里的“-1 were matched”实际是指没有匹配到任何符合条件的行，核心原因有这几个：

1. 行已被删除：你查询到user之后、commit之前，该行已经被其他会话/进程删除，导致UPDATE语句找不到ID=1的行。
2. 乐观锁版本不匹配：如果开启了version_id_col，你查询到user时的版本号，在commit前已经被其他操作修改，UPDATE语句的WHERE条件（ID+版本号）匹配不到任何行。
3. 会话/连接异常：比如当前会话的数据库连接已失效，或者查询和更新不在同一个事务上下文（不过你的代码用的是同一个session，这种情况概率极低）。

你的更新命令可能存在的问题排查 #

从代码逻辑看本身没问题，但可以按以下步骤排查：

• 在commit前加一行检查：print(session.query(User).filter_by(id=1).count())，确认行是否还存在。
• 如果启用了乐观锁，查看user对象的version字段在修改前后的变化，或者是否有其他操作修改了该字段。
• 尝试显式刷新会话：修改字段后执行session.refresh(user)，如果行已被删除，这会直接抛出NotFoundError，提前发现问题。
• 检查数据库的user表是否有主键约束，确保ID=1的行确实存在，且主键未被篡改。

内容的提问来源于stack exchange，提问作者half of a glazier