FastAPI + PostgreSQL 性能调优：索引策略与连接池优化

在实际项目中，数据库往往是 API 的性能瓶颈。本文从索引设计、查询优化和连接池配置三个维度，拆解 FastAPI 项目中 PostgreSQL 性能调优的实战经验。

在 FastAPI 项目进入生产环境后，随着数据量从几千行增长到百万级别，你会发现原本毫秒级响应的接口突然开始「卡顿」。排查之后，十有八九问题出在数据库层。这篇文章总结我在实际项目中遇到和解决的 PostgreSQL 性能问题，覆盖索引策略、查询优化和连接池配置三个核心维度。

ORM 生成的 SQL 不总是最优

SQLAlchemy 是 FastAPI 生态中最常用的 ORM，它极大地提升了开发效率，但代价是「你不再完全掌控生成的 SQL」。一个经典的坑是 N+1 查询：当你遍历一个关系对象时，SQLAlchemy 会为每条记录再发一次查询。

# ❌ 错误：导致 N+1 查询
users = db.query(User).all()
for user in users:
    print(user.posts)  # 每次循环都触发一次查询

# ✅ 正确：使用 joinedload 或 selectinload
from sqlalchemy.orm import joinedload
users = db.query(User).options(joinedload(User.posts)).all()

在开发环境中数据量小，你不会察觉；一到生产环境，1000 个用户就是 1001 次数据库往返——延迟从 50ms 飙升到 3 秒以上。

EXPLAIN ANALYZE 的正确使用姿势

优化查询的第一步永远是测量，而不是猜测。EXPLAIN ANALYZE 是 PostgreSQL 最强大的诊断工具，但很多人只看执行时间，忽略了更关键的指标。

执行 EXPLAIN ANALYZE 时，核心关注点有三个：

Seq Scan（全表扫描）：在大表上出现时几乎一定需要加索引
rows 估算 vs actual rows：差距过大说明统计信息过期，需要 ANALYZE table_name;
cost 的相对比例：找到占比最高的节点，优先优化

EXPLAIN ANALYZE
SELECT * FROM orders
WHERE user_id = 42 AND status = 'pending'
ORDER BY created_at DESC
LIMIT 20;

-- 输出中关注：
--  Seq Scan on orders  (cost=0.00..1543.00 rows=5 width=...)
--                        ^^^^ 如果 rows 估算偏差巨大，说明统计过期

复合索引 vs 单列索引的选择策略

索引不是越多越好。每多一个索引，写入操作就要多维护一棵 B-Tree。选择策略的核心原则是：为查询模式设计索引，而不是为表设计索引。

对于上面的查询 WHERE user_id = 42 AND status = 'pending' ORDER BY created_at，最优解是一个覆盖索引：

CREATE INDEX idx_orders_user_status_created
ON orders (user_id, status, created_at DESC);

复合索引的列顺序非常关键：等值条件在前，范围条件在后，排序字段放最后。如果把 status 放在 user_id 前面，当只按 user_id 查询时这个索引就用不上。

我的经验法则是：先用单列索引覆盖最高频的等值查询，出现慢查询时通过 EXPLAIN 分析，再针对性加复合索引。

SQLAlchemy 连接池参数调优

连接池配置直接影响高并发场景下的数据库吞吐。SQLAlchemy 默认的连接池大小是 5，对于 API 服务来说远远不够。关键参数有四个：

from sqlalchemy import create_engine
from sqlalchemy.pool import QueuePool

engine = create_engine(
    "postgresql+asyncpg://user:pass@host/db",
    pool_size=20,          # 常驻连接数
    max_overflow=10,       # pool_size 满后可额外创建的连接数
    pool_recycle=3600,     # 连接最大存活时间（秒），避免 PG 主动断开
    pool_pre_ping=True,    # 每次使用前检测连接是否有效
)

pool_size 的设置公式通常是 (CPU 核心数 × 2) + 有效磁盘数，但并不绝对——需要结合压测结果调整。pool_recycle 一定要小于 PostgreSQL 服务端的 idle_in_transaction_session_timeout，否则会出现「连接已被服务端关闭但客户端不知道」的错误。

asyncpg 替代 psycopg2 的性能差异

如果你还在用 psycopg2，切换到 asyncpg 是性价比最高的优化之一。asyncpg 是一个纯 Python 实现的异步 PostgreSQL 驱动，它通过直接实现 PostgreSQL 的二进制协议来避免不必要的序列化开销。

在我的一次基准测试中，同样的查询在 100 并发下：

psycopg2 + SQLAlchemy 同步模式：平均延迟 320ms，P99 延迟 1.2s
asyncpg + SQLAlchemy 异步模式：平均延迟 85ms，P99 延迟 230ms

提升接近 4 倍。需要注意的是，切换到 asyncpg 要求你的整个数据库访问链路都使用 async/await，包括 FastAPI 的路由处理函数、SQLAlchemy 的异步 session、以及 Alembic 迁移脚本。虽然迁移有一定成本，但对于 IO 密集型的 API 服务来说，这笔投资非常值得。

总结

数据库性能优化是一个「测量 → 分析 → 优化 → 再测量」的循环。最常犯的错误是在没有数据支撑的情况下「凭感觉」加索引或调参数。把 EXPLAIN ANALYZE 和压测工具（如 wrk、Locust）融入你的日常开发流程，让每一次优化都有据可依。