---
title: Installation
description: Install pg_stat_ch from prebuilt binaries or build from source
---

## 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.

<Steps>
  <Step title="Download the tarball">
    Go to the [latest release](https://github.com/ClickHouse/pg_stat_ch/releases/latest) and download the tarball matching your PostgreSQL version and architecture. For example, for PostgreSQL 18 on amd64:

    ```bash
    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` |
  </Step>
  <Step title="Extract and install">
    ```bash
    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/
    ```
  </Step>
</Steps>

See `INSTALL.md` in the tarball for full instructions.

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

## 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:

```bash
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](https://mise.jdx.dev) installed:

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

Other build targets:

```bash
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

```bash
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`:

```bash
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.

<Steps>
  <Step title="Edit postgresql.conf">
    ```ini
    shared_preload_libraries = 'pg_stat_ch'
    ```

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

    ```ini
    shared_preload_libraries = 'pg_stat_statements, pg_stat_ch'
    ```
  </Step>
  <Step title="Restart PostgreSQL">
    ```bash
    sudo systemctl restart postgresql
    ```
  </Step>
  <Step title="Create the extension in each database you want to monitor">
    ```sql
    CREATE EXTENSION pg_stat_ch;
    ```
  </Step>
</Steps>

## Verify installation

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

```sql
-- 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`.

## Recommended PostgreSQL settings

These PostgreSQL settings are not required but provide more data:

```ini
# Enable I/O timing (small overhead, big value)
track_io_timing = on

# Enable query ID computation (required for query grouping)
compute_query_id = on

# Enable JIT stats collection
jit = on
```

## Next steps

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

<CardGroup cols={2}>
  <Card title="Quick start" icon="bolt" href="/get-started/quick-start">
    Docker-based setup that gets you from zero to querying events in ClickHouse
  </Card>
  <Card title="ClickHouse setup" icon="database" href="/guides/clickhouse">
    Production ClickHouse deployment, schema, and data retention
  </Card>
  <Card title="OpenTelemetry export" icon="signal-stream" href="/guides/opentelemetry">
    Route telemetry through your existing OTel collector to Grafana, Datadog, etc.
  </Card>
  <Card title="Configuration" icon="gear" href="/reference/configuration">
    Tune queue size, flush interval, and connection settings
  </Card>
</CardGroup>