Installation

Prerequisites

PostgreSQL 16, 17, or 18
Docker and Docker Compose (for the quickstart and ClickHouse setup)
ClickHouse (for the default export backend) or an OpenTelemetry collector

Install from prebuilt binaries

Prebuilt binaries are published for every release on Linux (amd64 and arm64) for PostgreSQL 16, 17, and 18.

Download the tarball

Go to the latest release and download the tarball matching your PostgreSQL version and architecture. For example, for PostgreSQL 18 on amd64:

curl -LO https://github.com/ClickHouse/pg_stat_ch/releases/latest/download/pg_stat_ch-v0.3.4-pg18-linux-amd64.tar.gz

Available variants:

PostgreSQL	amd64	arm64
16	`pg_stat_ch-*-pg16-linux-amd64.tar.gz`	`pg_stat_ch-*-pg16-linux-arm64.tar.gz`
17	`pg_stat_ch-*-pg17-linux-amd64.tar.gz`	`pg_stat_ch-*-pg17-linux-arm64.tar.gz`
18	`pg_stat_ch-*-pg18-linux-amd64.tar.gz`	`pg_stat_ch-*-pg18-linux-arm64.tar.gz`

Extract and install

tar -xzf pg_stat_ch-*.tar.gz
cd pg_stat_ch-*/
sudo cp pg_stat_ch.so $(pg_config --pkglibdir)/
sudo cp pg_stat_ch.control pg_stat_ch--*.sql $(pg_config --sharedir)/extension/

See INSTALL.md in the tarball for full instructions.

Debug symbol packages (*-debuginfo.tar.gz) are also available for crash analysis. Extract and point gdb at the debug directory.

Build from source

Building from source requires CMake 3.20+, Ninja (or Make), a C++17 compiler (GCC 10+, Clang 13+), and PostgreSQL development headers (postgresql-server-dev-*). Clone the repository with submodules:

git clone --recurse-submodules https://github.com/ClickHouse/pg_stat_ch.git
cd pg_stat_ch

Using mise (recommended for development)

If you have mise installed:

mise run build        # Debug build against the default pg_config
mise run install      # Install into the PostgreSQL extension directory

Other build targets:

mise run build:release    # Optimized release build
mise run build:16         # Build for PostgreSQL 16
mise run build:17         # Build for PostgreSQL 17
mise run build:18         # Build for PostgreSQL 18
mise run build:all        # Build for all supported versions

Using CMake directly

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
sudo cmake --install build

To target a specific PostgreSQL installation, pass -DPG_CONFIG:

cmake -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DPG_CONFIG=/usr/lib/postgresql/18/bin/pg_config
cmake --build build
sudo cmake --install build

Load the extension

pg_stat_ch must be loaded via shared_preload_libraries because it needs to initialize at server startup.

Edit postgresql.conf

shared_preload_libraries = 'pg_stat_ch'

If you already have other extensions loaded, add pg_stat_ch to the comma-separated list:

shared_preload_libraries = 'pg_stat_statements, pg_stat_ch'

Restart PostgreSQL

sudo systemctl restart postgresql

Create the extension in each database you want to monitor

CREATE EXTENSION pg_stat_ch;

Verify installation

Check that the extension is loaded and the background worker is running:

-- Check version
SELECT pg_stat_ch_version();

-- Check stats (queue should be active)
SELECT * FROM pg_stat_ch_stats();

-- Check the background worker is visible
SELECT pid, application_name, state, wait_event
FROM pg_stat_activity
WHERE application_name = 'pg_stat_ch exporter';

If the background worker doesn’t appear, check the PostgreSQL log for errors. The most common issue is forgetting to add pg_stat_ch to shared_preload_libraries.

Next steps

With the extension loaded, connect it to a backend to start receiving events:

Quick start

Docker-based setup that gets you from zero to querying events in ClickHouse

ClickHouse setup

Production ClickHouse deployment, schema, and data retention

OpenTelemetry export

Route telemetry through your existing OTel collector to Grafana, Datadog, etc.

Configuration

Tune queue size, flush interval, and connection settings

Get started

Guides

Reference

Prerequisites

Install from prebuilt binaries

Build from source

Using mise (recommended for development)

Using CMake directly

Load the extension

Verify installation

Recommended PostgreSQL settings

Next steps

Quick start

ClickHouse setup

OpenTelemetry export

Configuration

​Prerequisites

​Install from prebuilt binaries

​Build from source

​Using mise (recommended for development)

​Using CMake directly

​Load the extension

​Verify installation

​Recommended PostgreSQL settings

​Next steps

Quick start

ClickHouse setup

OpenTelemetry export

Configuration

Prerequisites

Install from prebuilt binaries

Build from source

Using mise (recommended for development)

Using CMake directly

Load the extension

Verify installation

Recommended PostgreSQL settings

Next steps