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:19
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 consultas TPC-H entre tabelas PostgreSQL convencionais e o pg_clickhouse conectado ao ClickHouse, ambos carregados com fator de escala 1; ✔︎ indica pushdown completo em uma única varredura externa, e ✼ indica pushdown completo em várias varreduras externas. Todos os testes foram executados em um MacBook Pro M4 Max com 36 GB de memória.

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

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