documentação de referência do pg_clickhouse

Introdução

pg_clickhouse, uma extensão de código aberto do PostgreSQL, executa consultas analíticas no ClickHouse diretamente do PostgreSQL, sem reescrever nenhum SQL. Ela é compatível com PostgreSQL 13 e versões posteriores e ClickHouse v23 e versões posteriores. Assim que ClickPipes começar a sincronizar dados para o ClickHouse, use o pg_clickhouse para [importar tabelas estrangeiras] de forma rápida e fácil para um schema do PostgreSQL. Em seguida, execute suas consultas existentes do PostgreSQL nessas tabelas, preservando sua base de código atual enquanto delega a execução ao ClickHouse.

Primeiros passos

A forma mais simples de experimentar o pg_clickhouse é a [imagem Docker], que contém a imagem Docker padrão do PostgreSQL com as extensões pg_clickhouse e 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 o tutorial para começar a importar tabelas do ClickHouse e fazer pushdown de consultas.

Caso de teste: TPC-H

Esta tabela compara o desempenho das TPC-H queries entre tabelas PostgreSQL comuns e o pg_clickhouse conectado ao ClickHouse, ambos carregados com fator de escala 1; ✔︎ indica pushdown completo, enquanto um traço indica o cancelamento de uma consulta após 1 min. Todos os testes foram executados em um MacBook Pro M4 Max com 36 GB de memória.

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 do código-fonte

Unix em geral

Os pacotes de desenvolvimento do PostgreSQL e do curl incluem pg_config e curl-config no path, então você deve conseguir simplesmente executar make (ou gmake), depois make install e, em seguida, no seu banco de dados, CREATE EXTENSION pg_clickhouse.

Debian / Ubuntu / APT

Consulte PostgreSQL Apt para ver detalhes sobre como obter pacotes do repositório PostgreSQL Apt.

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

Consulte PostgreSQL Yum para obter detalhes sobre como baixar pacotes do repositório PostgreSQL Yum.

Instalar via PGXN

Com as dependências acima atendidas, use o PGXN client (disponível como pacotes Homebrew, Apt e Yum chamados pgxnclient) para baixar, compilar e instalar pg_clickhouse:

pgxn install pg_clickhouse

Compilar e instalar

Para compilar e instalar a biblioteca ClickHouse e pg_clickhouse, execute:

make
sudo make install

Se o host tiver várias instalações do PostgreSQL, talvez seja necessário especificar a versão correta do pg_config:

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

Se curl-config não estiver no path do seu host, você pode especificar o path explicitamente:

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

Se você se deparar com um erro como:

"Makefile", line 8: Need an operator

Você precisa usar o GNU make, que pode estar instalado no seu sistema como gmake:

gmake
gmake install
gmake installcheck

Se você se deparar com um erro como:

make: pg_config: Command not found

Certifique-se de que o pg_config esteja instalado e no seu path. Se você usou um sistema de gerenciamento de pacotes, como RPM, para instalar o PostgreSQL, certifique-se de que o pacote -devel também esteja instalado. Se necessário, informe ao processo de build onde encontrá-lo:

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

Para instalar a extensão em um prefixo personalizado no PostgreSQL 18 ou superior, passe o argumento prefix para install (mas não para outros alvos de make):

sudo make install prefix=/usr/local/extras

Em seguida, certifique-se de que o prefixo esteja incluído nos seguintes [parâmetros do postgresql.conf]:

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

Testes

Para executar a suíte de testes, após instalar a extensão, execute

make installcheck

Se você encontrar um erro como:

ERROR:  must be owner of database regression

Você precisa executar a suíte de testes com um superusuário, como o superusuário padrão “postgres”:

make installcheck PGUSER=postgres

Carregando

Depois que pg_clickhouse estiver instalado, você poderá adicioná-lo a um banco de dados conectando-se como superusuário e executando:

CREATE EXTENSION pg_clickhouse;

Se você quiser instalar o pg_clickhouse e todos os seus objetos auxiliares em um schema específico, use a cláusula SCHEMA para especificar o schema, assim:

CREATE SCHEMA env;
CREATE EXTENSION pg_clickhouse SCHEMA env;

Dependências

A extensão pg_clickhouse requer PostgreSQL 13 ou superior, libcurl e libuuid. A compilação da extensão requer compiladores C e C++, libSSL, GNU make e CMake.

Roadmap

Nosso principal foco é concluir a cobertura de pushdown para cargas de trabalho analíticas antes de adicionar recursos de DML. Nosso roadmap:

Planejar de forma ideal as 10 consultas TPC-H restantes que ainda não têm pushdown
Testar e corrigir o pushdown das consultas do ClickBench
Oferecer suporte ao pushdown transparente de todas as funções de agregação do PostgreSQL
Oferecer suporte ao pushdown transparente de todas as funções do PostgreSQL
Permitir configurações do ClickHouse no nível do servidor e da sessão via CREATE SERVER e GUCs
Oferecer suporte a todos os tipos de dados do ClickHouse
Oferecer suporte a DELETEs leves e UPDATEs
Oferecer suporte à inserção em lote via COPY
Adicionar uma função para executar uma consulta arbitrária do ClickHouse e retornar seus resultados como uma tabela
Adicionar suporte ao pushdown de consultas UNION quando todas forem executadas no banco de dados remoto

Autores

Direitos autorais

​Introdução

​Primeiros passos

​Caso de teste: TPC-H

​Compilar a partir do código-fonte

​Unix em geral

​Debian / Ubuntu / APT

​RedHat / CentOS / Yum

​Instalar via PGXN

​Compilar e instalar

​Testes

​Carregando

​Dependências

​Roadmap

​Autores

​Direitos autorais