pg_clickhouse

pg_clickhouse : Interfaces to query ClickHouse databases from PostgreSQL

Overview

Packages

Source

pig build pkg pg_clickhouse;		# build rpm/deb

Install

Make sure PGDG and PIGSTY repo available:

pig repo add pgsql -u   # add both repo and update cache

Install this extension with pig:

pig install pg_clickhouse;		# install via package name, for the active PG version

pig install pg_clickhouse -v 18;   # install for PG 18
pig install pg_clickhouse -v 17;   # install for PG 17
pig install pg_clickhouse -v 16;   # install for PG 16
pig install pg_clickhouse -v 15;   # install for PG 15
pig install pg_clickhouse -v 14;   # install for PG 14

Config this extension to shared_preload_libraries:

shared_preload_libraries = 'pg_clickhouse';

Create this extension with:

CREATE EXTENSION pg_clickhouse;

Usage

Syntax:

CREATE EXTENSION pg_clickhouse;
CREATE SERVER taxi_srv FOREIGN DATA WRAPPER clickhouse_fdw
  OPTIONS(driver 'binary', host 'localhost', dbname 'taxi');
CREATE USER MAPPING FOR CURRENT_USER SERVER taxi_srv OPTIONS (user 'default');
IMPORT FOREIGN SCHEMA taxi FROM SERVER taxi_srv INTO taxi;

Sources: README, Reference, Tutorial

pg_clickhouse is a PostgreSQL extension for running analytics queries on ClickHouse directly from PostgreSQL, including a foreign data wrapper and query pushdown support. The current upstream docs state support for PostgreSQL 13+ and ClickHouse 23+.

Getting Started

The upstream project documents two common starting points:

• use the published Docker image ghcr.io/clickhouse/pg_clickhouse:18
• build with make / make install or install from PGXN

Once installed, enable the extension:

CREATE EXTENSION pg_clickhouse;

Or install it into a dedicated schema:

CREATE SCHEMA ch;
CREATE EXTENSION pg_clickhouse WITH SCHEMA ch;

Connecting to ClickHouse

The reference docs show the normal flow as:

CREATE SERVER taxi_srv
FOREIGN DATA WRAPPER clickhouse_fdw
OPTIONS (driver 'binary', host 'localhost', dbname 'taxi');

CREATE USER MAPPING FOR CURRENT_USER
SERVER taxi_srv
OPTIONS (user 'default');

CREATE SCHEMA taxi;
IMPORT FOREIGN SCHEMA taxi FROM SERVER taxi_srv INTO taxi;

Documented server options include:

• driver, required, either binary or http
• dbname
• fetch_size
• host
• port

What the Docs Emphasize

The README positions pg_clickhouse around transparent pushdown for analytic workloads. It links both a tutorial and a SQL reference:

• the tutorial walks through connecting PostgreSQL to a ClickHouse sample database and querying imported tables
• the reference documents extension lifecycle commands, foreign server options, and SQL objects exposed by the extension

The project README also includes TPC-H benchmark examples showing where pushdown can significantly reduce runtime.

Operational Notes

The reference docs describe versioning separately for:

• the library version, visible via pgch_version() or pg_get_loaded_modules()
• the extension version tracked by PostgreSQL catalogs and extension upgrade scripts

Minor and major upgrades can require ALTER EXTENSION pg_clickhouse UPDATE.