SQLAlchemy2.0异步迁移教程

SQLAlchemy 2.0 的异步迁移远不止语法升级，而是一场从同步思维到协程调度意识的深度转变：async_sessionmaker 不是即用型会话而是需 await 调用的协程工厂，所有数据库操作（execute、commit、rollback）都必须显式 await 否则形同虚设；select 查询必须通过 await session.execute() 获取结果，再调用 scalars().all() 等同步方法，切不可沿用同步模式的链式调用；异步引擎必须使用 create_async_engine 配套专用驱动（如 asyncpg、aiosqlite）和 NullPool 连接池，普通引擎和线程安全池会直接报错；事务管理更需谨慎——跨 await 边界混用 begin/commit/rollback 极易导致状态混乱，推荐统一采用 async with session.begin(): 保障边界清晰。漏掉任何一个 await，整个异步链路就会静默挂起，看似运行却无实际效果，调试困难却后果严重。

async_sessionmaker 创建后必须配 await，不能直接调用

SQLAlchemy 2.0 的异步支持不是“打开开关就自动变快”，而是把整个执行链路推到协程里。最常见错误是写完 async_sessionmaker 还像以前一样 session = async_session()，结果得到一个 AsyncSession 实例——但这个实例所有操作（add、commit、execute）都返回协程对象，不 await 就永远不真正执行。

• 正确姿势：用 async with async_session() as session: 或显式 await session.commit()
• 错误现象：RuntimeWarning: coroutine 'AsyncSession.commit' was never awaited，或查询返回空结果、事务不生效
• 注意 async_sessionmaker 本身不创建会话，它生成的是可 await 的工厂；每次调用都需 await 才拿到活跃会话

select() 查询必须用 await session.execute()，不能用 session.scalars()

同步模式下常用 session.scalars(select(...)).all()，但异步模式下没有等价的阻塞式 scalars()。直接调用会报 AttributeError: 'AsyncScalarResult' object has no attribute 'all'——因为返回的是惰性迭代器，底层仍是协程封装。

• 必须写成：result = await session.execute(select(User))，再用 result.scalars().all()（注意 all() 是同步方法，但前面的 execute 必须 await）
• 如果只取单条：(await session.execute(select(User).limit(1))).scalar_one_or_none()
• 别漏掉 await：session.execute() 返回 AsyncResult，不是结果本身；没 await 就只是个未调度的协程对象

engine.connect() 在 async 模式下要换 asyncio.create_engine()

旧代码里用 create_engine("sqlite:///db.db") 配合 sessionmaker，迁移到异步时不能复用。普通 engine 不支持 async，强行传给 async_sessionmaker 会触发 AsyncEngine expected 类型错误。

• 必须改用：create_async_engine("sqlite+aiosqlite:///db.db", echo=True)（SQLite 需 aiosqlite）、postgresql+asyncpg://... 等带 async driver 的 URL
• driver 兼容性很关键：MySQL 要 aiomysql 或 asyncmy，PostgreSQL 强烈推荐 asyncpg（psycopg 3.1+ 才支持 async）
• 连接池参数也不同：AsyncEngine 的 poolclass 必须是 NullPool（默认），不能用 QueuePool —— 后者是线程安全设计，和 asyncio event loop 冲突

嵌套 await 和事务边界容易出错

异步事务不像同步那样靠上下文管理器“自动兜底”。比如在函数 A 中 await session.commit()，然后调用函数 B 做另一组操作，B 里再 await session.rollback()，可能因 session 已关闭或状态混乱导致 InvalidRequestError: This Session's transaction is closed。

• 事务边界必须显式对齐：要么整个业务逻辑包在一个 async with session.begin(): 里，要么确保每个 commit/rollback 都对应一次独立的 begin()
• 避免跨 await 边界传递 session 并混用 begin() 和手动 commit()；更安全的做法是让每个协程函数自己管理自己的事务块
• 特别注意 ORM 关系加载：selectinload 和 joinedload 在 async 下行为一致，但 lazy='select' 触发的隐式查询仍需 await，容易漏掉

异步迁移最难的不是语法替换，而是把“线性执行预期”扭转为“协程调度意识”——session 不是资源句柄，是协程上下文；execute 不是动作，是调度请求；commit 不是落盘，是等待事件循环轮到它执行。漏掉一个 await，整条链就卡住不动，还很难 debug。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。