Documentación de referencia de pg_clickhouse

Introducción

[pg_clickhouse], una extensión de PostgreSQL de código abierto, ejecuta consultas analíticas en ClickHouse directamente desde PostgreSQL sin necesidad de reescribir SQL. Es compatible con PostgreSQL 13 y versiones posteriores, y con ClickHouse v23 y posteriores.

Una vez que ClickPipes comience a sincronizar datos con ClickHouse, usa pg_clickhouse para importar tablas foráneas de forma rápida y sencilla a un esquema de PostgreSQL. Luego, ejecuta tus consultas existentes de PostgreSQL sobre esas tablas, conservando tu base de código actual mientras delegas la ejecución en ClickHouse.

Primeros pasos

La forma más sencilla de probar pg_clickhouse es la imagen de Docker, que incluye la imagen estándar de PostgreSQL para Docker junto con las extensiones pg_clickhouse y 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'

Consulta el tutorial para empezar a importar tablas de ClickHouse y delegar la ejecución de consultas.

Caso de prueba: TPC-H

Esta tabla compara el rendimiento de las consultas TPC-H entre tablas PostgreSQL convencionales y pg_clickhouse conectado a ClickHouse, ambos con un factor de escalado de 1; ✔︎ indica un pushdown completo con un único escaneo externo y ✼ indica un pushdown completo con varios escaneos externos. Todas las pruebas se ejecutaron en un MacBook Pro M4 Max con 36 GB de memoria.

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

Compilar a partir del código fuente

Unix en general

Los paquetes de desarrollo de PostgreSQL y curl incluyen pg_config y curl-config en el PATH, por lo que debería bastar con ejecutar make (o gmake), luego make install y, después, en tu base de datos CREATE EXTENSION pg_clickhouse.

Debian / Ubuntu / APT

Consulta PostgreSQL Apt para obtener más información sobre cómo descargarlo desde el repositorio 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

Consulta PostgreSQL Yum para obtener más información sobre cómo descargar desde el repositorio PostgreSQL Yum.

Instalar desde PGXN

Con las dependencias anteriores ya cumplidas, use el PGXN client (disponible como paquetes de Homebrew, Apt y Yum llamados pgxnclient) para descargar, compilar e instalar pg_clickhouse:

pgxn install pg_clickhouse

Compilar e instalar

Para compilar e instalar la biblioteca de ClickHouse y pg_clickhouse, ejecute:

make
sudo make install

Si el host tiene varias instalaciones de PostgreSQL, es posible que deba especificar la versión correcta de pg_config:

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

Si curl-config no está en el PATH de su host, puede especificar la ruta explícitamente:

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

Si aparece un error como este:

"Makefile", line 8: Need an operator

Debe usar GNU make, que puede estar instalado en su sistema como gmake:

gmake
gmake install
gmake installcheck

Si aparece un error como este:

make: pg_config: Command not found

Asegúrate de que pg_config esté instalado y disponible en tu path. Si usaste un sistema de gestión de paquetes como RPM para instalar PostgreSQL, asegúrate de que el paquete -devel también esté instalado. Si es necesario, indícale al proceso de compilación dónde encontrarlo:

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

Para instalar la extensión en un prefijo personalizado en PostgreSQL 18 o posterior, pase el argumento prefix a install (pero no a ningún otro objetivo de make):

sudo make install prefix=/usr/local/extras

A continuación, asegúrese de que se incluya el prefijo en los siguientes [postgresql.conf parámetros]:

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

Pruebas

Para ejecutar la batería de pruebas, una vez instalada la extensión, ejecute

make installcheck

Si aparece un error como este:

ERROR:  must be owner of database regression

Necesita ejecutar el conjunto de pruebas con un superusuario, como el superusuario predeterminado "postgres":

make installcheck PGUSER=postgres

Carga

Una vez instalado pg_clickhouse, puede añadirlo a una base de datos conectándose como superusuario y ejecutando:

CREATE EXTENSION pg_clickhouse;

Si quieres instalar pg_clickhouse y todos sus objetos de soporte en un esquema específico, utiliza la cláusula SCHEMA para especificar el esquema, así:

CREATE SCHEMA env;
CREATE EXTENSION pg_clickhouse SCHEMA env;

Dependencias

La extensión pg_clickhouse requiere PostgreSQL 13 o superior, libcurl y libuuid. Para compilar la extensión se necesita un compilador de C y C++, libSSL, GNU make y CMake.

Hoja de ruta

Nuestra principal prioridad es completar la cobertura de pushdown para cargas de trabajo analíticas antes de añadir capacidades de DML. Nuestra hoja de ruta:

Lograr una planificación óptima para las 10 consultas TPC-H restantes sin pushdown
Probar y corregir el pushdown para las consultas de ClickBench
Admitir el pushdown transparente de todas las funciones de agregación de PostgreSQL
Admitir el pushdown transparente de todas las funciones de PostgreSQL
Permitir ajustes de ClickHouse a nivel de servidor y de sesión mediante CREATE SERVER y GUCs
Admitir todos los tipos de datos de ClickHouse
Admitir eliminaciones ligeras y UPDATEs
Admitir inserción por lotes mediante COPY
Añadir una función para ejecutar una consulta arbitraria de ClickHouse y devolver sus resultados en forma de tabla
Añadir compatibilidad con el pushdown de consultas UNION cuando todas consulten la base de datos remota

Autores

Derechos de autor