SQLAlchemy2.x异步事务管理技巧

SQLAlchemy 2.x 原生支持异步数据库操作，但必须严格使用 AsyncSession 配合 async with session.begin() 进行事务管理——从创建异步引擎（如 asyncpg）、构建异步 session 工厂，到显式开启事务、正确 await 所有操作、禁用 lazy loading 并预加载关联数据，每一步都与同步模式截然不同；本文直击异步开发中极易踩坑的核心实践，帮你避开事务失效、await 忘记、session 复用等常见陷阱，真正用好 SQLAlchemy 的异步能力。

<p>SQLAlchemy 2.x 原生支持异步，需用 <strong>AsyncSession</strong> 配合 <strong>async with</strong> 实现事务上下文管理，不能直接复用同步的 <code>sessionmaker</code>。</p>

<H3>1. 创建异步引擎和 session 工厂</H3>
<p>必须使用 <code>create_async_engine</code>，并指定异步驱动（如 <code>postgresql+asyncpg</code>、<code>mysql+aiomysql</code>）：</p>
<font color="#888">
<pre><code>from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker

# 异步引擎（注意 driver！）
engine = create_async_engine(
    "postgresql+asyncpg://user:pass@localhost/db",
    echo=True,
    pool_pre_ping=True,
)

# 异步 session 工厂（不是 session 实例！）
AsyncSessionLocal = async_sessionmaker(
    bind=engine,
    expire_on_commit=False,  # 异步下推荐设为 False，避免 await 后对象过期
)</code>

2. 使用 async with 管理事务生命周期

AsyncSession 本身不自动开启事务，需显式用 async with session.begin() 进入事务上下文。成功则自动 commit，异常则 rollback：

<code>from sqlalchemy.exc import SQLAlchemyError

async def create_user(name: str, email: str):
    async with AsyncSessionLocal() as session:
        try:
            async with session.begin():  # ✅ 关键：显式开启事务
                user = User(name=name, email=email)
                session.add(user)
                # 可继续 add / delete / execute 等操作
                await session.flush()  # 可选：获取插入后的主键（如 user.id）
                return user.id
        except SQLAlchemyError:
            # session 已自动 rollback，无需手动调用
            raise
</code>

3. 手动控制 commit/rollback（进阶场景）

若需在事务中分阶段提交（如保存部分状态），可用 session.commit() 和 session.rollback()，但必须确保最终退出时事务已结束：

• 用 async with session.begin_nested() 支持 savepoint（嵌套事务）
• 显式调用 await session.commit() 后，该事务段即结束，后续操作属于新事务
• 手动 commit/rollback 后，不能再对同一 session 调用 begin() —— 应改用新 session 或重新 begin

4. 注意事项

• 所有数据库操作（add、execute、scalars、scalar、all 等）都必须 await
• 对象延迟加载（lazy loading）在异步 session 中默认禁用，需显式用 selectinload 或 joinedload 预加载
• 不要在异步 session 中混用同步方法（如 session.query() 已废弃）
• 关闭引擎用 await engine.dispose()，而非 engine.dispose()

今天关于《SQLAlchemy2.x异步事务管理技巧》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！