PostgREST 性能调试实战:借助 pg_stat_statements 定位慢查询

原创2026-09-10 13:11:511,868 阅读
文章标签:后端Web框架认证鉴权API设计

PostgREST 性能调试实战:借助 pg_stat_statements 定位慢查询

PostgREST 将 HTTP 请求编译为动态 SQL 再交给 PostgreSQL 执行,因此传统的应用侧慢查询定位手段并不完全适用。本文介绍如何通过 PostgREST 内置的 PLAN 请求(Accept: application/vnd.pgrst.plan)拿到某次请求对应的查询标识符(Query Identifier),再回到 pg_stat_statements 中关联该标识符,获取调用次数、执行耗时、返回行数等真实运行时统计,从而把"某个 URL 请求慢"精确对应到"某条 PostgreSQL 查询慢"。读完本文,你将掌握一套从 PostgREST 请求到 PostgreSQL 查询级的完整性能排查链路。

前置条件

在开始之前,请确认以下两个前提同时满足,否则下面的步骤无法执行:

  1. 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。

  2. 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() 被清空。

第三步:完整排查流程示例

将两步串起来,一套可复用的排查流程如下:

  1. 对疑似慢的接口发起一次 PLAN 请求拿到 Query Identifier:
curl "http://localhost:3000/projects?select=id,name&order=id" \
  -H "Accept: application/vnd.pgrst.plan+json; options=verbose"
  1. 用 Query Identifier 在数据库中查询该查询的历史统计:
select calls, total_exec_time, mean_exec_time, rows
from pg_stat_statements
where queryid = -432192689578025496;
  1. 结合 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),从而为索引优化、查询重写和参数调优提供可靠依据。

登录后查看全文
postgrest