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. Ele oferece suporte ao PostgreSQL 13 e posteriores e ao ClickHouse v23 e posteriores. Assim que o ClickPipes começar a sincronizar dados com o ClickHouse, use o pg_clickhouse para [importar tabelas estrangeiras] com rapidez e facilidade para um schema do PostgreSQL. Em seguida, execute suas consultas PostgreSQL existentes nessas tabelas, preservando sua base de código atual e fazendo pushdown da execução para o ClickHouse.

Primeiros passos

A forma mais simples de testar 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 usar pushdown de consultas.

Caso de teste: TPC-H

Esta tabela compara o desempenho das consultas TPC-H 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, portanto 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 extrair do repositório Apt do 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

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

Instale pelo PGXN

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

pgxn install pg_clickhouse

Compilar e instalar

Para compilar e instalar a biblioteca ClickHouse e o 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 host, você pode especificar o path explicitamente:

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

Se você encontrar 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 ocorrer um erro como o seguinte:

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, verifique se o pacote -devel também está instalado. Se necessário, informe ao processo de compilação 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 posterior, passe o argumento prefix para install (mas não para nenhum outro alvo do make):

sudo make install prefix=/usr/local/extras

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

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, depois que a extensão estiver instalada, execute

make installcheck

Se você encontrar um erro como:

ERROR:  must be owner of database regression

Você precisa executar a suíte de testes usando 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 objetos de suporte 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 posterior, libcurl, libuuid. Para compilar a extensão, é necessário um compilador C e C++, libSSL, GNU make e CMake.

Roteiro

Nosso foco principal é concluir a cobertura de pushdown para workloads analíticas antes de adicionar recursos de DML. Nosso roteiro:

Fazer com que as 10 consultas TPC-H restantes sem pushdown sejam planejadas de forma ideal
Testar e corrigir o pushdown para as 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 em nível de servidor e de 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 tabelas
Adicionar suporte ao pushdown de consultas UNION quando todas consultarem o 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

​Instale pelo PGXN

​Compilar e instalar

​Testes

​Carregando

​Dependências

​Roteiro

​Autores

​Direitos autorais