VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
选择异步驱动
SQLAlchemy 2.0 为两个异步 MySQL 驱动提供方言:asyncmy 和 aiomysql。文档没有把其中任何一个列为相对另一个的官方推荐。asyncmy 是用 Cython 编写的编译型驱动,为当前的 Python 版本提供预构建的 wheel,这就是本指南使用它的原因:
sqlalchemy 而不是 sqlalchemy[asyncio] 是第一个真正的陷阱。SQLAlchemy 的异步 ORM 层用 greenlet 库桥接异步和同步代码,而它不是基础包的依赖。跳过 [asyncio] 附加项,在您第一次使用异步引擎时就会产生这个错误:
pip install greenlet,或者更好的做法是,始终带 [asyncio] 附加项安装 SQLAlchemy,这样它会被自动拉入。
第二个陷阱是 cryptography。MySQL 8 和 VillageSQL 的新账户默认使用 caching_sha2_password 身份验证插件,它需要 RSA 密钥交换,以便在给定账户第一次从给定客户端库进行身份验证时发送密码。asyncmy 不捆绑 RSA 实现,所以必须完成这次完整握手的连接会失败并报错:
mysql CLI),服务器就会缓存结果,之后的连接会走跳过 RSA 步骤的更快路径,这就是为什么这个错误看起来时有时无,取决于最近是什么连接了该账户。预先安装 cryptography 完全消除了对该缓存的依赖,是可靠的修复方法。
创建数据库和用户
创建专用的数据库和应用用户,而不是以 root 身份连接:127.0.0.1,而不是 localhost。本指南中的连接字符串通过 TCP 连接到 127.0.0.1,所以授权必须与该主机匹配;Unix 套接字连接则匹配 localhost,与账户基于 IP 的授权无关。
项目布局
requirements.txt:
异步引擎与会话
app/database.py 创建异步引擎、会话工厂,以及每个模型使用的声明式基类:
expire_on_commit=False 对 FastAPI 很重要。使用默认的 expire_on_commit=True 时,已提交对象上的每个属性都会被标记为过期,下一次读取该属性会发出一条新的 SELECT 来刷新它。如果这次刷新是在 await 之外触发的,它会失败并报错:
expire_on_commit=False 使对象上已加载的值在提交后仍然可用,从而避免了这两种情况。
get_session() 是一个生成器函数,这让 FastAPI 的 Depends() 能在请求结束后自动关闭会话,无论请求成功还是抛出异常。
模型
app/models.py 使用 SQLAlchemy 2.0 的类型化声明式风格(Mapped 和 mapped_column)而不是旧的仅 Column 风格来定义 Post 表:
server_default=func.now() 把时间戳默认值交给 MySQL 本身,所以即使是在应用程序之外插入的行,它也能被正确设置。
设置 Alembic
使用异步模板初始化 Alembic,它会生成一个已经为异步引擎接好线的env.py:
init 的路径是什么,Alembic 都会把 alembic.ini 写到当前工作目录,尽管 alembic/ 脚本文件夹本身是在给定路径创建的。在错误的目录中运行它会在意想不到的地方留下一个多余的 alembic.ini。
把 alembic.ini 指向实际的数据库:
alembic/env.py 以导入模型,让 autogenerate 能看到它们:
Pydantic 模式
app/schemas.py 独立于 ORM 模型定义请求和响应的形状:
from_attributes=True 让 PostRead 直接从 Post ORM 实例而不是字典构建响应。
FastAPI 路由
app/main.py 通过 Depends() 把会话接入每个路由,所以每个请求都获得自己的会话,而不是共享一个全局连接:
Depends() 为每个请求创建的会话避免了这一点,因为每个请求都获得自己的会话和自己从池中取出的连接。
运行与验证
启动应用:常见问题
为什么异步引擎需要与同步引擎不同的连接字符串?
连接字符串中的驱动名称告诉 SQLAlchemy 加载哪个 DBAPI。同步设置使用mysql+pymysql:// 或 mysql+mysqldb://;异步设置需要基于 asyncio 构建的驱动,所以字符串改用 mysql+asyncmy://。把同步驱动名称用于 create_async_engine 会立即失败,因为该驱动没有可供 SQLAlchemy 调用的异步接口。
我需要 expire_on_commit=False 吗?
不是严格必需,但如果跳过它,对已提交对象的每次属性访问都会触发一次新的数据库往返来重新加载它,而这次往返只有在活动的异步上下文内发生时才有效。取决于属性具体在哪里被读取,这会表现为 MissingGreenlet,或者在会话关闭后表现为 DetachedInstanceError。对 Web 应用来说,更安全的默认值是 expire_on_commit=False。
我还能使用 Alembic 的同步 autogenerate 工作流吗?
可以。异步模板的env.py 仍然从常规命令行运行 revision --autogenerate 和 upgrade;异步部分只影响 env.py 如何打开自己的连接来检查和修改模式。Alembic CLI 命令本身没有任何变化。
故障排除
另请参阅
- 在 ORM 中使用 MySQL:Django、Rails 和 Prisma — 同样的字符集和严格模式配置也适用于 SQLAlchemy
- MySQL 连接池 — 为并发 FastAPI 请求下的异步引擎调整池大小