Psycopg 已经可以完成所有数据库操作,但项目规模扩大以后,如果每个函数都要手动处理连接、游标、结果转换和重复 SQL,维护成本会逐渐增加。SQLAlchemy 建立在数据库驱动之上,帮助应用统一组织 SQL、连接、事务和对象映射。
SQLAlchemy 在驱动之上提供两套相关能力:
Core 和 ORM 不是两套互不相关的技术。ORM 建立在 Core 之上,最终仍然把 Python 操作转换成 SQL,再通过 Psycopg 发送给 PostgreSQL。它不会取代数据库约束,也不会让我们可以忽略 SQL 和执行计划。
同一个项目也不必在 Core 和 ORM 之间二选一。常规的增删改查可以使用 ORM 组织对象,批量更新、复杂统计或 PostgreSQL 专用语句则可以直接使用 Core 表达式。选择依据是查询是否清楚、可维护,而不是强制所有 SQL 都写成同一种形式。
FastAPI 业务代码可以通过 SQLAlchemy ORM 管理对象,ORM 建立在 Core 之上。Core、Engine、Pool 与 Dialect 组织 SQL、事务和连接,再由 Psycopg 驱动与 PostgreSQL 通信。业务也可直接使用 Core,ORM 不会取代数据库约束。
FLOW / RELATIONSHIP
FastAPI 业务代码
SQLAlchemy ORM
对象映射与状态管理
SQLAlchemy Core
Engine · Pool · Dialect
Psycopg
实际数据库通信
PostgreSQL
安装 SQLAlchemy 与 Psycopg:
1uv add "sqlalchemy[asyncio]>=2.0,<3" "psycopg[binary]>=3.2"
asyncio 额外项会确保 greenlet 等 SQLAlchemy 异步功能需要的依赖可用。接下来使用 DeclarativeBase 创建声明基类,并通过 Mapped 和 mapped_column() 定义类型化模型。
asyncio
greenlet
DeclarativeBase
Mapped
mapped_column()
对于刚接触 SQLAlchemy 的读者,可以先记住接下来几篇文章的分工:Engine 负责连接数据库,声明式模型描述表与 Python 类的对应关系,Session 则负责一次业务操作中的查询、对象状态和事务。本篇先完成前两部分,下一篇再进入 Session。
Engine 是应用访问数据库的入口,它包含方言和连接池。异步 FastAPI 项目使用 create_async_engine():
create_async_engine()
1from sqlalchemy.ext.asyncio import create_async_engine 2 3from app.core.settings import settings 4 5 6engine = create_async_engine( 7 settings.database_url, 8 pool_pre_ping=True, 9)
配置中的 URL 使用 SQLAlchemy 方言格式:
1DATABASE_URL=postgresql+psycopg://task_app:task_app_dev_password@127.0.0.1:5432/task_app
这段 URL 可以拆成下面几部分:
postgresql
psycopg
task_app:task_app_dev_password
127.0.0.1:5432
task_app
postgresql 选择 PostgreSQL 方言,psycopg 选择驱动。与 create_async_engine() 组合后,SQLAlchemy 会使用 Psycopg 的异步实现。同一个 postgresql+psycopg:// 方言也支持同步 Engine,究竟使用同步还是异步实现,由 create_engine() 或 create_async_engine() 决定。
postgresql+psycopg://
create_engine()
如果用户名或密码中含有 @、:、/ 等 URL 特殊字符,需要进行百分号编码,不能直接拼进 URL。应用代码也不应把完整数据库 URL 写入日志,因为其中通常包含密码。
@
:
/
这里可以把 Engine 的职责拆成三个部分理解:
这里创建出来的对象是 AsyncEngine。它通常是进程级长生命周期对象,不应该在每个请求中重复创建。调用 create_async_engine() 时一般也不会立刻连接数据库,第一次真正取得连接或执行 SQL 时,连接池才会建立连接。因此,仅仅导入模块或启动应用没有报错,并不能证明数据库 URL 一定可用。
AsyncEngine
可以执行一条轻量查询检查连接:
1from sqlalchemy import text 2 3from app.db.engine import engine 4 5 6async def check_database() -> bool: 7 async with engine.connect() as connection: 8 value = await connection.scalar(text("SELECT 1")) 9 return value == 1
engine.connect() 从连接池取得一条连接,离开上下文时再归还。SQLAlchemy 2.x 默认会在第一次执行语句时自动开始事务;这里是只读检查,连接归还前会结束事务。需要提交写入时,应使用 engine.begin()、显式事务或下一篇介绍的 Session 事务,不能把关闭连接误解为自动提交。
engine.connect()
engine.begin()
pool_pre_ping=True 会在连接池借出连接时检查它是否仍然可用,减少数据库重启或网络断开后拿到失效连接的问题。它会增加一次轻量检查,但不能挽救执行到一半时断开的事务;这种情况仍会抛出异常,应用必须回滚,并根据操作的幂等性决定是否重试整个事务。
pool_pre_ping=True
应用关闭时应执行 await engine.dispose(),让连接池主动关闭空闲连接。这个操作属于 FastAPI lifespan 的关闭阶段,而不是每个请求的清理步骤:
await engine.dispose()
01from collections.abc import AsyncIterator 02from contextlib import asynccontextmanager 03 04from fastapi import FastAPI 05 06from app.db.engine import engine 07 08 09@asynccontextmanager 10async def lifespan(_app: FastAPI) -> AsyncIterator[None]: 11 try: 12 yield 13 finally: 14 await engine.dispose() 15 16 17app = FastAPI(lifespan=lifespan)
连接池容量、worker 数量和 PostgreSQL 的连接上限要一起规划,不能把每个进程的池大小孤立看待。这里暂时使用默认池配置,生产环境中的 pool_size、max_overflow 和超时设置会在部署章节单独讨论。
pool_size
max_overflow
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 认识 SQLAlchemy
Psycopg 已经可以完成所有数据库操作,但项目规模扩大以后,如果每个函数都要手动处理连接、游标、结果转换和重复 SQL,维护成本会逐渐增加。SQLAlchemy 建立在数据库驱动之上,帮助应用统一组织 SQL、连接、事务和对象映射。
SQLAlchemy 在驱动之上提供两套相关能力:
Core 和 ORM 不是两套互不相关的技术。ORM 建立在 Core 之上,最终仍然把 Python 操作转换成 SQL,再通过 Psycopg 发送给 PostgreSQL。它不会取代数据库约束,也不会让我们可以忽略 SQL 和执行计划。
同一个项目也不必在 Core 和 ORM 之间二选一。常规的增删改查可以使用 ORM 组织对象,批量更新、复杂统计或 PostgreSQL 专用语句则可以直接使用 Core 表达式。选择依据是查询是否清楚、可维护,而不是强制所有 SQL 都写成同一种形式。
FastAPI 业务代码可以通过 SQLAlchemy ORM 管理对象,ORM 建立在 Core 之上。Core、Engine、Pool 与 Dialect 组织 SQL、事务和连接,再由 Psycopg 驱动与 PostgreSQL 通信。业务也可直接使用 Core,ORM 不会取代数据库约束。
FLOW / RELATIONSHIP
FastAPI 业务代码
SQLAlchemy ORM
对象映射与状态管理
SQLAlchemy Core
Engine · Pool · Dialect
Psycopg
实际数据库通信
PostgreSQL
安装 SQLAlchemy 与 Psycopg:
asyncio额外项会确保greenlet等 SQLAlchemy 异步功能需要的依赖可用。接下来使用DeclarativeBase创建声明基类,并通过Mapped和mapped_column()定义类型化模型。对于刚接触 SQLAlchemy 的读者,可以先记住接下来几篇文章的分工:Engine 负责连接数据库,声明式模型描述表与 Python 类的对应关系,Session 则负责一次业务操作中的查询、对象状态和事务。本篇先完成前两部分,下一篇再进入 Session。
2. Engine
Engine 是应用访问数据库的入口,它包含方言和连接池。异步 FastAPI 项目使用
create_async_engine():配置中的 URL 使用 SQLAlchemy 方言格式:
这段 URL 可以拆成下面几部分:
postgresqlpsycopgtask_app:task_app_dev_password127.0.0.1:5432task_apppostgresql选择 PostgreSQL 方言,psycopg选择驱动。与create_async_engine()组合后,SQLAlchemy 会使用 Psycopg 的异步实现。同一个postgresql+psycopg://方言也支持同步 Engine,究竟使用同步还是异步实现,由create_engine()或create_async_engine()决定。如果用户名或密码中含有
@、:、/等 URL 特殊字符,需要进行百分号编码,不能直接拼进 URL。应用代码也不应把完整数据库 URL 写入日志,因为其中通常包含密码。这里可以把 Engine 的职责拆成三个部分理解:
这里创建出来的对象是
AsyncEngine。它通常是进程级长生命周期对象,不应该在每个请求中重复创建。调用create_async_engine()时一般也不会立刻连接数据库,第一次真正取得连接或执行 SQL 时,连接池才会建立连接。因此,仅仅导入模块或启动应用没有报错,并不能证明数据库 URL 一定可用。可以执行一条轻量查询检查连接:
engine.connect()从连接池取得一条连接,离开上下文时再归还。SQLAlchemy 2.x 默认会在第一次执行语句时自动开始事务;这里是只读检查,连接归还前会结束事务。需要提交写入时,应使用engine.begin()、显式事务或下一篇介绍的 Session 事务,不能把关闭连接误解为自动提交。pool_pre_ping=True会在连接池借出连接时检查它是否仍然可用,减少数据库重启或网络断开后拿到失效连接的问题。它会增加一次轻量检查,但不能挽救执行到一半时断开的事务;这种情况仍会抛出异常,应用必须回滚,并根据操作的幂等性决定是否重试整个事务。应用关闭时应执行
await engine.dispose(),让连接池主动关闭空闲连接。这个操作属于 FastAPI lifespan 的关闭阶段,而不是每个请求的清理步骤:连接池容量、worker 数量和 PostgreSQL 的连接上限要一起规划,不能把每个进程的池大小孤立看待。这里暂时使用默认池配置,生产环境中的
pool_size、max_overflow和超时设置会在部署章节单独讨论。