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

Sources: README, reference, tutorial, v0.2.0 release notes

pg_clickhouse runs analytics queries on ClickHouse from PostgreSQL through the clickhouse_fdw foreign data wrapper. Upstream documents PostgreSQL 13+ and ClickHouse 23+ support.

Connect PostgreSQL to ClickHouse

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');

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

Server options documented upstream:

• driver: required, binary or http
• host
• port
• dbname
• fetch_size: HTTP streaming batch size; 0 disables streaming

User mapping options:

• user
• password

Common operations

ALTER EXTENSION pg_clickhouse UPDATE;
ALTER EXTENSION pg_clickhouse UPDATE TO '0.2';
DROP SERVER taxi_srv CASCADE;

IMPORT FOREIGN SCHEMA also supports LIMIT TO (...) and EXCEPT (...). The reference warns that imported mixed-case identifiers are double-quoted in PostgreSQL and must be queried with quotes.

Version and pushdown notes

• The reference documents separate library and extension versions; pgch_version() was added in release v0.2.0.
• Patch-only releases update the library without requiring ALTER EXTENSION.
• Release v0.2.0 added more pushdown for arrays, regex functions, split_part(), array operators, and current date/time expressions, plus the pg_clickhouse.pushdown_regex setting.

Caveats

• This is positioned upstream as an analytics-first extension; the roadmap still lists broader DML support as future work.
• For full examples, follow the official tutorial, which creates a ClickHouse taxi database, imports it through IMPORT FOREIGN SCHEMA, and queries the resulting foreign tables.