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 estándar de PostgreSQL y pg_clickhouse conectado a ClickHouse, ambos 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 una 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 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

Primeros pasos

Funciones

Benchmarks

Precios

ClickHouse Integration

Migraciones

Monitorización

FAQ

Documentación de referencia de pg_clickhouse

Introducción

Primeros pasos

Caso de prueba: TPC-H

Compilar a partir del código fuente

Unix en general

Debian / Ubuntu / APT

RedHat / CentOS / Yum

Instalar desde PGXN

Compilar e instalar

Pruebas

Carga

Dependencias

Hoja de ruta

Autores

Derechos de autor

​Introducción

​Primeros pasos

​Caso de prueba: TPC-H

​Compilar a partir del código fuente

​Unix en general

​Debian / Ubuntu / APT

​RedHat / CentOS / Yum

​Instalar desde PGXN

​Compilar e instalar

​Pruebas

​Carga

​Dependencias

​Hoja de ruta

​Autores

​Derechos de autor

Introducción

Primeros pasos

Caso de prueba: TPC-H

Compilar a partir del código fuente

Unix en general

Debian / Ubuntu / APT

RedHat / CentOS / Yum

Instalar desde PGXN

Compilar e instalar

Pruebas

Carga

Dependencias

Hoja de ruta

Autores

Derechos de autor