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 standard et pg_clickhouse connecté à ClickHouse, tous deux chargés avec un facteur d'échelle de 1 ; ✔︎ indique un pushdown complet effectué en un seul parcours de table étrangère, tandis que ✼ indique un pushdown complet effectué en plusieurs parcours de tables étrangères. Tous les tests ont été exécutés sur un MacBook Pro M4 Max doté de 36 Go de mémoire.

Requête	PostgreSQL	pg_clickhouse	Pushdown
[requête 1]	4483 ms	59 ms	✔
[requête 2]	588 ms	24 ms	✔
[requête 3]	786 ms	62 ms	✔
[requête 4]	550 ms	38 ms	✔
[requête 5]	721 ms	1439 ms	✔
[requête 6]	592 ms	17 ms	✔
[requête 7]	639 ms	29 ms	✔
[requête 8]	398 ms	383 ms	✔
[requête 9]	2842 ms	162 ms	✔
[requête 10]	860 ms	125 ms	✔
[requête 11]	276 ms	21 ms	✼
[requête 12]	963 ms	26 ms	✔
[requête 13]	1037 ms	1354 ms
[requête 14]	675 ms	30 ms	✔
[requête 15]	2520 ms	387 ms
[requête 16]	539 ms	823 ms
[requête 17]	2107 ms	37 ms	✔
[requête 18]	5230 ms	7228 ms
[requête 19]	68 ms	47 ms	✔
[requête 20]	473 ms	28 ms
[requête 21]	1145 ms	4470 ms
[requête 22]	270 ms	45 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 rencontrez une erreur telle que :

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 paramètres [postgresql.conf 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