Documentation de référence de pg_clickhouse

Introduction

[pg_clickhouse], une extension PostgreSQL open source, exécute des requêtes analytiques sur ClickHouse directement depuis PostgreSQL, sans réécrire le moindre SQL. Elle prend en charge PostgreSQL 13 et versions ultérieures, ainsi que ClickHouse v23 et versions ultérieures. Une fois que ClickPipes commence à synchroniser les données vers ClickHouse, utilisez pg_clickhouse pour import foreign tables rapidement et facilement dans un schéma PostgreSQL. Exécutez ensuite vos requêtes PostgreSQL existantes sur ces tables, sans modifier votre base de code existante, tout en déléguant l’exécution à ClickHouse.

Premiers pas

Le moyen le plus simple d’essayer pg_clickhouse est d’utiliser l’[image Docker], qui contient l’image Docker PostgreSQL standard avec les extensions pg_clickhouse et re2 :

docker run --name pg_clickhouse -e POSTGRES_PASSWORD=my_pass \
       -d ghcr.io/clickhouse/pg_clickhouse:19
docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhouse'

Consultez le [tutoriel] pour commencer à importer des tables ClickHouse et à déléguer l’exécution des requêtes.

Cas de test : TPC-H

Ce tableau compare les performances des requêtes TPC-H entre des tables PostgreSQL classiques et pg_clickhouse connecté à ClickHouse, tous deux chargés avec un facteur d’échelle de 1 ; ✔︎ indique un pushdown complet, tandis qu’un tiret indique l’annulation d’une requête après 1 min. Tous les tests ont été exécutés sur un MacBook Pro M4 Max avec 36 Go de mémoire.

Requête	PostgreSQL	pg_clickhouse	Pushdown
[Requête 1]	4693 ms	268 ms	✔︎
[Requête 2]	458 ms	3446 ms
[Requête 3]	742 ms	111 ms	✔︎
[Requête 4]	270 ms	130 ms	✔︎
[Requête 5]	337 ms	1460 ms	✔︎
[Requête 6]	764 ms	53 ms	✔︎
[Requête 7]	619 ms	96 ms	✔︎
[Requête 8]	342 ms	156 ms	✔︎
[Requête 9]	3094 ms	298 ms	✔︎
[Requête 10]	581 ms	197 ms	✔︎
[Requête 11]	212 ms	24 ms
[Requête 12]	1116 ms	84 ms	✔︎
[Requête 13]	958 ms	1368 ms
[Requête 14]	181 ms	73 ms	✔︎
[Requête 15]	1118 ms	557 ms
[Requête 16]	497 ms	1714 ms
[Requête 17]	1846 ms	32709 ms
[Requête 18]	5823 ms	10649 ms
[Requête 19]	53 ms	206 ms	✔︎
[Requête 20]	421 ms	-
[Requête 21]	1349 ms	4434 ms
[Requête 22]	258 ms	1415 ms

Compiler à partir des sources

Unix général

Les paquets de développement de PostgreSQL et de curl incluent pg_config et curl-config dans le PATH, vous devriez donc pouvoir simplement exécuter make (ou gmake), puis make install, puis dans votre base de données CREATE EXTENSION pg_clickhouse.

Debian / Ubuntu / APT

Voir PostgreSQL Apt pour plus de détails sur la récupération depuis le dépôt APT de PostgreSQL.

sudo apt install \
  postgresql-server-19 \
  libcurl4-openssl-dev \
  uuid-dev \
  libssl-dev \
  make \
  cmake \
  g++

RedHat / CentOS / Yum

sudo yum install \
  postgresql-server \
  libcurl-devel \
  libuuid-devel \
  openssl-libs \
  automake \
  cmake \
  gcc

Voir PostgreSQL Yum pour plus de détails sur la récupération des paquets depuis le dépôt Yum de PostgreSQL.

Installer depuis PGXN

Une fois les dépendances ci-dessus remplies, utilisez le PGXN client (disponible sous forme de paquets Homebrew, Apt et Yum nommés pgxnclient) pour télécharger, compiler et installer pg_clickhouse :

pgxn install pg_clickhouse

Compiler et installer

Pour compiler et installer la bibliothèque ClickHouse et pg_clickhouse, exécutez :

make
sudo make install

Si votre machine comporte plusieurs installations de PostgreSQL, vous devrez peut-être préciser la version appropriée de pg_config :

export PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config
make
sudo make install

Si curl-config n’est pas dans le PATH de votre hôte, vous pouvez spécifier le chemin explicitement :

export CURL_CONFIG=/opt/homebrew/opt/curl/bin/curl-config
make
sudo make install

Si vous rencontrez une erreur telle que :

"Makefile", line 8: Need an operator

Vous devez utiliser GNU make, qui peut être installé sur votre système sous le nom de gmake :

gmake
gmake install
gmake installcheck

Si vous obtenez une erreur du type :

make: pg_config: Command not found

Assurez-vous que pg_config est installé et présent dans votre path. Si vous avez utilisé un gestionnaire de paquets tel que RPM pour installer PostgreSQL, assurez-vous que le paquet -devel est également installé. Si nécessaire, indiquez au processus de compilation où le trouver :

export PG_CONFIG=/path/to/pg_config
make
sudo make install

Pour installer l’extension avec un préfixe personnalisé sur PostgreSQL 18 ou version ultérieure, spécifiez l’argument prefix pour install (mais pour aucune autre cible make) :

sudo make install prefix=/usr/local/extras

Assurez-vous ensuite que le préfixe figure dans les [postgresql.conf paramètres] suivants :

extension_control_path = '/usr/local/extras/postgresql/share:$system'
dynamic_library_path   = '/usr/local/extras/postgresql/lib:$libdir'

Tests

Pour exécuter la suite de tests, une fois l’extension installée, lancez

make installcheck

Si vous rencontrez une erreur du type :

ERROR:  must be owner of database regression

Vous devez exécuter la suite de tests avec un superutilisateur, par exemple le superutilisateur “postgres” par défaut :

make installcheck PGUSER=postgres

Activation

Une fois pg_clickhouse installé, vous pouvez l’ajouter à une base de données en vous connectant en tant que superutilisateur et en exécutant :

CREATE EXTENSION pg_clickhouse;

Si vous souhaitez installer pg_clickhouse et tous les objets associés dans un schéma spécifique, utilisez la clause SCHEMA pour le préciser, comme suit :

CREATE SCHEMA env;
CREATE EXTENSION pg_clickhouse SCHEMA env;

Dépendances

L’extension pg_clickhouse nécessite PostgreSQL 13 ou une version supérieure, ainsi que libcurl et libuuid. La compilation de l’extension requiert un compilateur C et C++, libSSL, GNU make et CMake.

Feuille de route

Notre priorité absolue est de finaliser la couverture du pushdown pour les charges de travail analytiques avant d’ajouter des fonctionnalités DML. Notre feuille de route :

Obtenir une planification optimale pour les 10 requêtes TPC-H restantes sans pushdown
Tester et corriger le pushdown pour les requêtes ClickBench
Prendre en charge le pushdown transparent de toutes les fonctions d’agrégation PostgreSQL
Prendre en charge le pushdown transparent de toutes les fonctions PostgreSQL
Autoriser les paramètres ClickHouse au niveau du serveur et de la session via CREATE SERVER et les GUC
Prendre en charge tous les types de données ClickHouse
Prendre en charge les opérations lightweight DELETE et UPDATE
Prendre en charge l’insertion par lot via COPY
Ajouter une fonction pour exécuter une requête ClickHouse arbitraire et renvoyer ses résultats sous forme de tables
Ajouter la prise en charge du pushdown des requêtes UNION lorsqu’elles interrogent toutes la base de données distante

Auteurs

Copyright

​Introduction

​Premiers pas

​Cas de test : TPC-H

​Compiler à partir des sources

​Unix général

​Debian / Ubuntu / APT

​RedHat / CentOS / Yum

​Installer depuis PGXN

​Compiler et installer

​Tests

​Activation

​Dépendances

​Feuille de route

​Auteurs

​Copyright