pg_clickhouse

Overview

release 0.3.0; SQL v0.3

Version

Build

You can build the RPM / DEB packages for pg_clickhouse using pig build:

pig build pkg pg_clickhouse         # build RPM / DEB packages

Install

You can install pg_clickhouse directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

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

Install the extension using pig or apt/yum/dnf:

• Install
• pig
• dnf
• apt

pig install pg_clickhouse;          # Install for current active PG version

pig ext install -y pg_clickhouse -v 18  # PG 18
pig ext install -y pg_clickhouse -v 17  # PG 17
pig ext install -y pg_clickhouse -v 16  # PG 16
pig ext install -y pg_clickhouse -v 15  # PG 15
pig ext install -y pg_clickhouse -v 14  # PG 14

dnf install -y pg_clickhouse_18       # PG 18
dnf install -y pg_clickhouse_17       # PG 17
dnf install -y pg_clickhouse_16       # PG 16
dnf install -y pg_clickhouse_15       # PG 15
dnf install -y pg_clickhouse_14       # PG 14

apt install -y postgresql-18-clickhouse   # PG 18
apt install -y postgresql-17-clickhouse   # PG 17
apt install -y postgresql-16-clickhouse   # PG 16
apt install -y postgresql-15-clickhouse   # PG 15
apt install -y postgresql-14-clickhouse   # PG 14

Preload:

shared_preload_libraries = 'pg_clickhouse';

Create Extension:

CREATE EXTENSION pg_clickhouse;

Usage

Sources: README, reference, tutorial, v0.3.0 release notes, changelog

pg_clickhouse runs analytics queries on ClickHouse from PostgreSQL through the clickhouse_fdw foreign data wrapper. Upstream documents PostgreSQL 13+ and ClickHouse 23+ support; Pigsty packages version 0.3.0 for PostgreSQL 14-18.

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.3';
SELECT pgch_version();
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.

Query and write notes

SELECT, EXPLAIN, prepared statements, INSERT, and COPY can operate on pg_clickhouse foreign tables. Use EXPLAIN (VERBOSE) to inspect the remote SQL that will be sent to ClickHouse.

EXPLAIN (VERBOSE)
SELECT node_id, count(*)
FROM logs
GROUP BY node_id;

INSERT INTO nodes(node_id, name, region, arch, os)
VALUES (9, 'west-node', 'us-west-2', 'amd64', 'Linux');

COPY into a foreign table is documented, but upstream notes that it currently uses INSERT statements because FDW batch insertion is still future work.

Version and pushdown notes

• The reference documents separate library and extension versions; pgch_version() reports the loaded library version.
• Patch-only releases update the library without requiring ALTER EXTENSION.
• Release v0.3.0 uses SQL version 0.3; run ALTER EXTENSION pg_clickhouse UPDATE TO '0.3' to apply its SQL-level privilege change.
• Release v0.3.0 adds pushdown for re2 functions, soundex(), two-argument levenshtein(), compatible to_char(timestamp[tz], fmt), selected builtin functions, and JSON/JSONB path operations.
• ClickHouse JSON maps to PostgreSQL jsonb or json; the binary driver’s JSON mapping requires ClickHouse 24.10 or later.
• pg_clickhouse.pushdown_regex controls built-in PostgreSQL regex pushdown. Upstream recommends considering the re2 extension for regex work that should push down directly.

Caveats

• In 0.3.0, clickhouse_raw_query(text, text) is no longer executable by PUBLIC; grant it only to roles that need ad-hoc ClickHouse queries.
• This is positioned upstream as an analytics-first extension; lightweight DELETE and UPDATE support remain on the roadmap.
• 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.