documentação de referência do pg_clickhouse

Execute consultas analíticas no ClickHouse diretamente do PostgreSQL sem precisar reescrever o SQL

​

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

• David E. Wheeler
• Ildus Kurbangaliev
• Ibrar Ahmed

​

Direitos autorais

• Copyright (c) 2025-2026, ClickHouse
• Partes com Copyright (c) 2023-2025, Ildus Kurbangaliev
• Partes com Copyright (c) 2019-2023, Adjust GmbH
• Partes com Copyright (c) 2012-2019, PostgreSQL Global Development Group

[Consulta 1] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/1.sql [Consulta 2] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/2.sql [Consulta 3] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/3.sql [Consulta 4] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/4.sql [Consulta 5] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/5.sql [Consulta 6] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/6.sql [Consulta 7] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/7.sql [Consulta 8] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/8.sql [Consulta 9] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/9.sql [Consulta 10] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/10.sql [Consulta 11] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/11.sql [Consulta 12] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/12.sql [Consulta 13] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/13.sql [Consulta 14] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/14.sql [Consulta 15] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/15.sql [Consulta 16] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/16.sql [Consulta 17] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/17.sql [Consulta 18] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/18.sql [Consulta 19] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/19.sql [Consulta 20] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/20.sql [Consulta 21] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/21.sql [Consulta 22] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/22.sql