Referencia de pg_clickhouse - ClickHouse Documentation

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 el SQL. Es compatible con PostgreSQL 13 y versiones posteriores, y con ClickHouse v23 y versiones posteriores. Una vez que ClickPipes comienza a sincronizar datos con ClickHouse, use pg_clickhouse para importar tablas foráneas de forma rápida y sencilla en un esquema de PostgreSQL. Luego ejecute sus consultas de PostgreSQL existentes sobre esas tablas, conservando su base de código actual mientras delega la ejecución en ClickHouse.

Primeros pasos

La forma más sencilla de probar pg_clickhouse es la [imagen de Docker], que se basa en la imagen estándar de Docker de PostgreSQL con las extensiones pg_clickhouse y re2:

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

Consulte el tutorial para empezar a importar tablas de ClickHouse y delegar consultas.

Caso de prueba: TPC-H

Esta tabla compara el rendimiento de las consultas de TPC-H entre tablas PostgreSQL convencionales y pg_clickhouse conectado a ClickHouse, ambos con datos cargados con un factor de escala de 1; ✔︎ indica pushdown completo, mientras que un guion indica la cancelación de una consulta tras 1 min. Todas las pruebas se ejecutaron en un MacBook Pro M4 Max con 36 GB de memoria.

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

Compilar a partir del código fuente

Unix (general)

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

Debian / Ubuntu / APT

Consulte PostgreSQL Apt para obtener más información sobre cómo descargar desde el repositorio APT de PostgreSQL.

sudo apt install \
  postgresql-server-18 \
  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 Yum de PostgreSQL.

Instalar desde PGXN

Con las dependencias anteriores ya cubiertas, use el PGXN client (disponible como paquetes de Homebrew, Apt y Yum con el nombre 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 su host tiene varias instalaciones de PostgreSQL, es posible que deba especificar la versión adecuada 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 tu host, puedes 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

Necesita usar GNU make, que podría estar instalado en su sistema como gmake:

gmake
gmake install
gmake installcheck

Si aparece un error como:

make: pg_config: Command not found

Asegúrese de que pg_config esté instalado y en el PATH. Si usó un gestor de paquetes como RPM para instalar PostgreSQL, asegúrese de que el paquete -devel también esté instalado. Si es necesario, indique 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 versiones posteriores, pase el argumento prefix a install (pero no a ningún otro objetivo de make):

sudo make install prefix=/usr/local/extras

Luego, asegúrese de incluir el prefijo en los siguientes [parámetros de postgresql.conf]:

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

Debe ejecutar el conjunto de pruebas con un superusuario, como el superusuario predeterminado “postgres”:

make installcheck PGUSER=postgres

Carga

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

CREATE EXTENSION pg_clickhouse;

Si desea instalar pg_clickhouse y todos sus objetos auxiliares en un esquema específico, use la cláusula SCHEMA para especificar el esquema, de la siguiente manera:

CREATE SCHEMA env;
CREATE EXTENSION pg_clickhouse SCHEMA env;

Dependencias

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

Hoja de ruta

Nuestro principal objetivo es completar la cobertura de pushdown para las cargas de trabajo analíticas antes de añadir funcionalidades de DML. Nuestra hoja de ruta:

Lograr una planificación óptima de 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 agregado de PostgreSQL
Admitir el pushdown transparente de todas las funciones de PostgreSQL
Permitir configuraciones de ClickHouse a nivel de servidor y de sesión mediante CREATE SERVER y GUCs
Admitir todos los tipos de datos de ClickHouse
Admitir DELETE con eliminación ligera y UPDATE
Admitir inserciones por lotes mediante COPY
Añadir una función para ejecutar una consulta arbitraria de ClickHouse y devolver sus resultados como tablas
Añadir compatibilidad con el pushdown de consultas UNION cuando todas consulten la base de datos remota

Autores

Derechos de autor

​Introducción

​Primeros pasos

​Caso de prueba: TPC-H

​Compilar a partir del código fuente

​Unix (general)

​Debian / Ubuntu / APT

​RedHat / CentOS / Yum

​Instalar desde PGXN

​Compilar e instalar

​Pruebas

​Carga

​Dependencias

​Hoja de ruta

​Autores

​Derechos de autor