pg_stat_ch

概览

freeze due to new vcpkg dependency stack

版本

构建

您可以使用 pig build 命令构建 pg_stat_ch 扩展的 RPM / DEB 包：

pig build pkg pg_stat_ch         # 构建 RPM / DEB 包

安装

您可以直接安装 pg_stat_ch 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

• 安装
• pig
• dnf
• apt

pig install pg_stat_ch;          # 当前活跃 PG 版本安装

pig ext install -y pg_stat_ch -v 18  # PG 18
pig ext install -y pg_stat_ch -v 17  # PG 17
pig ext install -y pg_stat_ch -v 16  # PG 16

dnf install -y pg_stat_ch_18       # PG 18
dnf install -y pg_stat_ch_17       # PG 17
dnf install -y pg_stat_ch_16       # PG 16

apt install -y postgresql-18-pg-stat-ch   # PG 18
apt install -y postgresql-17-pg-stat-ch   # PG 17
apt install -y postgresql-16-pg-stat-ch   # PG 16

预加载配置：

shared_preload_libraries = 'pg_stat_ch';

创建扩展：

CREATE EXTENSION pg_stat_ch;

用法

来源：README、0.3.6 发行版

pg_stat_ch 会捕获 PostgreSQL 的逐查询执行遥测，并通过共享内存队列和后台工作进程将原始事件导出到 ClickHouse。上游将它定位为 pg_stat_statements 的原始事件替代方案：聚合与看板交给 ClickHouse 处理，而不是留在 PostgreSQL 内部。

CREATE EXTENSION pg_stat_ch;

所需配置

pg_stat_ch 必须预加载，并指向一个 ClickHouse 数据库：

shared_preload_libraries = 'pg_stat_ch'
track_io_timing = on

pg_stat_ch.clickhouse_host = 'localhost'
pg_stat_ch.clickhouse_port = 9000
pg_stat_ch.clickhouse_database = 'pg_stat_ch'
pg_stat_ch.clickhouse_use_tls = on
pg_stat_ch.clickhouse_skip_tls_verify = off

README 说明 PostgreSQL 16、17 和 18 已完整支持；最新发行版是 2026-04-15 发布的 0.3.6。

SQL API

• pg_stat_ch_version() 返回扩展版本。
• pg_stat_ch_stats() 暴露队列与导出器计数器。
• pg_stat_ch_reset() 清空队列计数器。
• pg_stat_ch_flush() 立即触发一次导出刷新。

SELECT pg_stat_ch_version();
SELECT * FROM pg_stat_ch_stats();
SELECT pg_stat_ch_flush();

重要 GUC

• pg_stat_ch.enabled 控制是否采集。
• pg_stat_ch.queue_capacity 和 pg_stat_ch.string_area_size 用于调整共享内存缓冲区大小。
• pg_stat_ch.flush_interval_ms 和 pg_stat_ch.batch_max 控制导出节奏和批量大小。
• pg_stat_ch.log_min_elevel 控制捕获哪些错误。

捕获内容

• 查询耗时、返回行数、缓冲区使用、WAL 使用量和 CPU 时间。
• DML、DDL 和工具语句。
• SQLSTATE 和错误级别。
• PostgreSQL 15+ 的 JIT 指标。
• PostgreSQL 18+ 的并行工作进程统计。
• 应用名、客户端 IP，以及在上游截断限制内的查询文本。

0.3.6 发行版将规范化缓存替换为以 queryId 为键的 LRU 缓存，并将 OpenTelemetry SDK 替换为直接使用 protobuf 的导出器和采样支持。现有 SQL 用法仍围绕事件表、汇总视图，以及上面的重置/版本辅助函数。

注意事项

• 该设计在队列溢出时会主动丢弃事件，而不是阻塞前台查询路径。
• 创建 ClickHouse 模式是必需的部署步骤；上游快速入门脚本会自动加载，但手工部署必须单独加载该模式。
• 在 Pigsty 当前这次 RPM 刷新中，pg_stat_ch 面向 PostgreSQL 16-18，且仅覆盖 EL9/EL10；Debian/Ubuntu 包仍覆盖活跃目标上的 PostgreSQL 16-18。