如何禁用SQLAlchemy 2.0新持久化模型的延迟加载？

问题描述 #

程序接收SQLAlchemy模型实例，统计子对象数量时：

• 通过ORM的select()预加载关联记录，操作正常；
• 创建新对象并持久化后，在会话范围外传入消费函数，访问关联属性会触发DetachedInstanceError。

示例代码：

from sqlalchemy import Column, String, ForeignKey
from sqlalchemy.orm import DeclarativeBase, Mapped, relationship, sessionmaker, create_engine

class Base(DeclarativeBase):
    pass

class Customer(Base):
    __tablename__ = 'customers'
    customer_id: str = Column(String(36), primary_key=True)
    orders: Mapped['Order'] = relationship('Order', back_populates='customer')

class Order(Base):
    __tablename__ = 'orders'
    order_id: str = Column(String(36), primary_key=True)
    customer_id: str = Column(String(36), ForeignKey('customers.customer_id'))
    customer: Mapped['Customer'] = relationship('Customer', back_populates='orders')

# 初始化引擎和会话
engine = create_engine("sqlite:///test.db")
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()

customer = Customer()
print(customer.orders)  # 正常执行，返回空集合

session.add(customer)
session.commit()
session.close()

print(customer.orders)  # 触发DetachedInstanceError

原因分析 #

SQLAlchemy的关系属性默认采用**懒加载（lazy='select'）**策略：当访问关联属性时，会自动从数据库查询数据。但实例脱离会话后，无法再访问数据库连接，因此触发DetachedInstanceError。而预加载是在会话范围内就把关联数据加载到实例中，脱离会话后直接访问缓存数据，所以不会报错。

解决方案 #

1. 禁用关联的懒加载 #

直接修改关系定义，设置lazy='noload'，这样访问关联属性时不会尝试查询数据库，直接返回空集合（新创建的实例本身也没有关联数据）。适合不需要在会话外懒加载关联的场景：

class Customer(Base):
    __tablename__ = 'customers'
    customer_id: str = Column(String(36), primary_key=True)
    # 设置lazy='noload'禁用懒加载
    orders: Mapped['Order'] = relationship('Order', back_populates='customer', lazy='noload')

2. 在会话内预加载关联数据 #

如果需要保留懒加载能力，但确保脱离会话后能正常访问关联属性，可以在实例脱离会话前，主动预加载关联数据：

customer = Customer()
session.add(customer)
session.commit()

# 在会话内预加载orders属性
customer = session.query(Customer).options(relationship('orders')).get(customer.customer_id)
# 或者用refresh强制加载
# session.refresh(customer, attribute_names=['orders'])

session.expunge(customer)  # 让实例脱离会话
session.close()

print(customer.orders)  # 正常执行，返回预加载的空集合

3. 配置会话禁用commit后实例过期 #

设置会话的expire_on_commit=False，commit后实例不会被标记为过期，已加载的关联数据可以继续访问。注意：如果关联数据未加载，访问时仍会触发懒加载错误，适合需要在commit后保持实例可用的场景：

# 创建会话时设置expire_on_commit=False
Session = sessionmaker(bind=engine, expire_on_commit=False)
session = Session()

customer = Customer()
session.add(customer)
session.commit()
session.close()

print(customer.orders)  # 正常执行，返回空集合

4. 访问前检查实例状态 #

通过sqlalchemy.inspect()判断实例是否脱离会话，根据状态处理关联属性访问：

from sqlalchemy import inspect

def count_customer_orders(customer):
    # 检查实例是否脱离会话
    if inspect(customer).detached:
        # 脱离会话时返回默认值或自定义逻辑
        return 0
    return len(customer.orders)

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