pg_stat_ch

概览

Requires shared_preload_libraries = pg_stat_ch; README recommends track_io_timing = on.

版本

构建

您可以使用 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;

用法

语法：

CREATE EXTENSION pg_stat_ch;
SELECT pg_stat_ch_version();
SELECT * FROM pg_stat_ch_stats();

来源：README，博客文章

pg_stat_ch 会在 PostgreSQL 中捕获每条查询的执行遥测信息，并实时把原始事件导出到 ClickHouse。上游项目将其与 pg_stat_statements 对比：后者在 PostgreSQL 内聚合统计，而它把原始事件发送到 ClickHouse 进行下游分析。

架构

README 将数据流描述为：

PostgreSQL hooks -> shared memory queue -> background worker -> ClickHouse

上游明确强调的设计目标包括：

• 查询路径上不发生网络 I/O
• 通过固定大小环形缓冲区限制内存
• 导出原始事件，而不是在本地聚合
• 当队列溢出或 ClickHouse 不可用时优雅降级

配置

扩展必须预加载，并配置 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

在 PostgreSQL 重启并完成 ClickHouse schema 初始化后：

CREATE EXTENSION pg_stat_ch;

SQL API

README 记录了以下 SQL 函数：

• pg_stat_ch_version()
• pg_stat_ch_stats()
• pg_stat_ch_reset()

pg_stat_ch_stats() 会暴露队列和导出器计数器，便于确认事件是否已被捕获并刷出。

捕获内容

当前 README 说明支持捕获：

• 查询耗时与返回行数
• 缓冲区使用量与 WAL 使用量
• CPU 时间
• DML、DDL 和通用语句
• SQLSTATE 与错误级别
• PostgreSQL 15+ 的 JIT 信息
• PostgreSQL 18+ 的并行 worker 统计
• 诸如应用名和客户端 IP 等客户端上下文信息

项目目前声明对 PostgreSQL 16、17 和 18 提供完整支持。