Что такое `pg_stat_statements` в PostgreSQL?

Что такое pg_stat_statements

pg_stat_statements — стандартное расширение PostgreSQL (входит в contrib), которое накапливает статистику выполнения всех SQL-запросов, обработанных сервером. Каждый уникальный запрос идентифицируется по нормализованной форме (литералы заменяются на $1, $2, ...), что позволяет группировать вызовы одного и того же запроса с разными параметрами.

Подключение

Расширение требует явной загрузки на уровне сервера:

-- postgresql.conf
shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.max = 10000       -- максимум уникальных запросов
pg_stat_statements.track = all       -- all | top | none
pg_stat_statements.track_utility = on -- DDL, COPY и т.д.

После перезапуска сервера расширение создаётся в нужной базе:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Ключевые метрики представления

Представление pg_stat_statements (PostgreSQL 14+) содержит следующие важные колонки:

Практические запросы

Топ-10 запросов по суммарному времени

SELECT
  round(total_exec_time::numeric, 2) AS total_ms,
  calls,
  round(mean_exec_time::numeric, 2)  AS mean_ms,
  round(
    (100 * total_exec_time / sum(total_exec_time) OVER ())::numeric, 2
  ) AS pct,
  query
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 10;

Запросы с высоким cache miss ratio

SELECT
  query,
  shared_blks_hit,
  shared_blks_read,
  round(
    100.0 * shared_blks_read
    / NULLIF(shared_blks_hit + shared_blks_read, 0), 2
  ) AS miss_pct
FROM pg_stat_statements
WHERE shared_blks_hit + shared_blks_read > 1000
ORDER BY miss_pct DESC
LIMIT 10;

Сброс накопленной статистики

-- Полный сброс (суперпользователь)
SELECT pg_stat_statements_reset();

-- Сброс конкретного запроса (PostgreSQL 12+)
SELECT pg_stat_statements_reset(userid, dbid, queryid);

Важные нюансы для senior-уровня

• pg_stat_statements.track = top — по умолчанию в некоторых дистрибутивах; не отслеживает запросы внутри функций. all включает вложенные.
• queryid — нестабильный хеш: после pg_upgrade или изменения схемы может измениться, нельзя использовать как долгосрочный ключ.
• Производительность: overhead минимален (~1–3%), но при max меньше реального числа уникальных запросов старые записи вытесняются — следите за pg_stat_statements_info.dealloc.
• PostgreSQL 13 добавил разделение total_exec_time на total_plan_time и total_exec_time; в ранних версиях планирование не выделялось отдельно.