PostgREST 性能调试实战:借助 pg_stat_statements 定位慢查询
PostgREST 性能调试实战:借助 pg_stat_statements 定位慢查询
PostgREST 将 HTTP 请求编译为动态 SQL 再交给 PostgreSQL 执行,因此传统的应用侧慢查询定位手段并不完全适用。本文介绍如何通过 PostgREST 内置的 PLAN 请求(Accept: application/vnd.pgrst.plan)拿到某次请求对应的查询标识符(Query Identifier),再回到 pg_stat_statements 中关联该标识符,获取调用次数、执行耗时、返回行数等真实运行时统计,从而把"某个 URL 请求慢"精确对应到"某条 PostgreSQL 查询慢"。读完本文,你将掌握一套从 PostgREST 请求到 PostgreSQL 查询级的完整性能排查链路。
前置条件
在开始之前,请确认以下两个前提同时满足,否则下面的步骤无法执行:
-
PostgREST 侧:必须开启
db-plan-enabled配置项。它默认关闭(False),其作用是允许通过Accept: application/vnd.pgrst.plan请求头获取某次请求的执行计划。开启方式有三种:- 配置文件:在 PostgREST 配置文件中写入
db-plan-enabled = true(默认配置模板中该项以注释形式存在,见 Config.hs); - 环境变量:
PGRST_DB_PLAN_ENABLED=true; - 数据库内配置:
pgrst.db_plan_enabled(仅当db-config开启时生效)。
该配置项为 Boolean 类型、可热重载(Reloadable: Y),完整参数说明见 configuration.rst。
- 配置文件:在 PostgREST 配置文件中写入
-
PostgreSQL 侧:版本需为 14 或更高,且已安装并启用
pg_stat_statements扩展。pg_stat_statements的queryid字段从 PostgreSQL 14 开始稳定可用,本文的关联查询依赖它。
注意:
db-plan-enabled只是开关,真正生成计划的能力在源码中始终存在。PostgREST 内部通过EXPLAIN (FORMAT JSON ...)包装实际查询来生成计划,其中FORMAT与各选项由请求中的媒体类型参数决定,见 SqlFragment.hs 的explainF实现。
第一步:从 PostgREST 获取查询标识符
开启配置并重启(或热重载)PostgREST 后,对任意 GET 请求追加 PLAN 媒体类型,即可让 PostgREST 返回该请求对应查询的执行计划,而不是真实数据。请求时在 Accept 头中指定 application/vnd.pgrst.plan+json,并附加 options=verbose 选项:
curl "http://localhost:3000/projects?select=id,name&order=id" \
-H "Accept: application/vnd.pgrst.plan+json; options=verbose"
这里 application/vnd.pgrst.plan+json 表示以 JSON 格式返回计划;options=verbose 对应 PostgreSQL EXPLAIN 的 VERBOSE 选项,它会让计划中包含顶层 Query Identifier 字段。响应大致如下:
[
{
"Plan": {
"Node Type": "Aggregate"
},
"Query Identifier": -432192689578025496
}
]
响应中的 Query Identifier 字段,其数值与 PostgreSQL 14+ 中 pg_stat_statements.queryid 的记录值一致,这正是两套系统之间的"关联键"。
关于 options 参数,源码中 explainF 支持的选项映射如下(见 SqlFragment.hs):
| options 值 | 对应 EXPLAIN 选项 | 说明 |
|---|---|---|
verbose |
VERBOSE |
输出更详细计划信息,包含 Query Identifier |
analyze |
ANALYZE |
实际执行查询并统计真实耗时与行数 |
settings |
SETTINGS |
输出影响该查询的参数设置 |
buffers |
BUFFERS |
输出缓冲区命中/读取信息(依赖 ANALYZE) |
wal |
WAL |
输出 WAL 写入统计(依赖 ANALYZE) |
多个选项用 | 分隔,例如 options=analyze|verbose|settings|buffers|wal。媒体类型解析器对上述取值均有对应实现,参见 MediaType.hs 中的 doctest 示例。仓库的端到端测试 PlanSpec.hs 也验证了 buffers、settings 等选项能正确返回对应内容。
此外,PostgREST 还支持 application/vnd.pgrst.plan+text(返回文本格式的计划)以及不带 +json/+text 后缀的 application/vnd.pgrst.plan(默认按文本处理),解析逻辑见 MediaType.hs。计划功能对读取、写入(POST/PATCH/DELETE)与 RPC 调用同样适用——从源码结构看,凡是进入 dbActionPlan 的动作,只要媒体类型为 MTVndPlan,都会被标记为需要执行 EXPLAIN,见 Plan.hs。
第二步:在 pg_stat_statements 中查询运行时统计
拿到 Query Identifier 后,直接用它过滤 pg_stat_statements 视图即可。继续使用上一步得到的 -432192689578025496:
select
calls,
total_exec_time,
mean_exec_time,
rows,
query
from pg_stat_statements
where queryid = -432192689578025496;
查询结果示例(各列含义见下文说明):
| calls | total_exec_time | mean_exec_time | rows | query |
|---|---|---|---|---|
| 13 | 0.6355850000000001 | 0.04889115384615385 | 13 | WITH pgrst_source AS (...) |
注意 query 列中记录的是 PostgreSQL 归一化(normalized)后的 SQL 文本,以 WITH pgrst_source AS (...) 开头——这是 PostgREST 生成 SQL 时使用的统一源 CTE 名称(sourceCTEName,见 SqlFragment.hs 与 Plan.hs 中对根节点 newFrom 的改写逻辑),多个不同的 HTTP 请求只要生成的 SQL 结构相同,就会共享同一条 pg_stat_statements 记录。
各列字段的业务含义
calls:该查询(含相同归一化文本的所有实例)被执行的总次数,用于判断"慢"是偶发还是持续高频;total_exec_time:累计执行总耗时(毫秒),是衡量该查询总体开销的核心指标;mean_exec_time:平均单次执行耗时(毫秒),可据此评估单次请求的平均延迟贡献;rows:该查询实际返回的行数,用于与业务预期对比,判断是否因缺少过滤条件而返回了过多数据;query:PostgreSQL 记录的归一化 SQL 原文,可直接阅读 PostgREST 究竟为某个 URL 生成了怎样的 SQL。
若需进一步定位,还可以在 pg_stat_statements 中继续取 max_exec_time、min_exec_time、stddev_exec_time 等列观察执行时间波动,或者结合 pg_stat_statements_info 检查统计重置时间,判断数据是否因 pg_stat_statements_reset() 被清空。
第三步:完整排查流程示例
将两步串起来,一套可复用的排查流程如下:
- 对疑似慢的接口发起一次 PLAN 请求拿到
Query Identifier:
curl "http://localhost:3000/projects?select=id,name&order=id" \
-H "Accept: application/vnd.pgrst.plan+json; options=verbose"
- 用
Query Identifier在数据库中查询该查询的历史统计:
select calls, total_exec_time, mean_exec_time, rows
from pg_stat_statements
where queryid = -432192689578025496;
- 结合
query列中的归一化 SQL 与EXPLAIN ANALYZE(或再次使用options=analyze的 PLAN 请求)对比计划估算与实际执行,确认瓶颈是缺失索引、行数估算偏差还是过滤条件不足。
值得说明的是,"返回执行计划"这一能力本身就自带两种用法:不带 ANALYZE 时只做计划不执行(零副作用,适合生产环境轻量排查);加上 options=analyze 时则会真实执行查询并输出实际耗时、行数与缓冲区统计。测试 PlanSpec.hs 验证了普通计划请求会返回大于 0 的 Total Cost,而 buffers 选项会返回 Shared Hit Blocks 等缓冲区信息,可作为核对输出内容是否正确的参考。
常见问题与注意事项
- 拿不到
Query Identifier字段:请确认请求头中确实带有options=verbose,并且服务端已开启db-plan-enabled = true。未开启时 PostgREST 会直接拒绝 PLAN 类型的请求。 pg_stat_statements查询为空:确认 PostgreSQL 版本 ≥ 14,且shared_preload_libraries中已加载pg_stat_statements(修改该参数需要重启数据库实例);另外请确认查询确实执行过(calls > 0),或者统计信息刚被重置。queryid为 NULL 的条目:PostgreSQL 14+ 对部分语句(如事务控制、PREPARE 等)可能不分配queryid,但 PostgREST 生成的普通 SELECT/INSERT/UPDATE/DELETE 均在可统计范围内。- 数值为负数:
Query Identifier是带符号 64 位整数,负数属正常现象,直接原样用于WHERE queryid = ...即可。 - 与真实请求 SQL 的对应关系:
pg_stat_statements中的记录按归一化 SQL 聚合,PostgREST 为不同 URL 生成的 SQL 只要文本模板一致就会归入同一条记录。如需精确到单次请求,应结合calls与时间窗口判断,或搭配 PostgREST 的请求日志一起分析。
小结
PostgREST 把"URL → SQL"的转换封装在内部,而 PLAN 媒体类型(Accept: application/vnd.pgrst.plan+json; options=verbose)恰好暴露了这条转换链路的产物:通过响应中的 Query Identifier 与 pg_stat_statements 的 queryid 建立一一对应关系,即可把 HTTP 层的一次慢请求精确映射到 PostgreSQL 层的真实执行统计(调用次数、总耗时、平均耗时、返回行数、归一化 SQL),从而为索引优化、查询重写和参数调优提供可靠依据。