Справочная документация по pg_clickhouse

Выполняйте аналитические запросы в ClickHouse прямо из PostgreSQL без переписывания SQL

​

Введение

[pg_clickhouse] — это PostgreSQL-расширение с открытым исходным кодом, которое позволяет выполнять аналитические запросы в ClickHouse прямо из PostgreSQL без переписывания SQL. Оно поддерживает PostgreSQL 13 и более поздних версий, а также ClickHouse v23 и более поздних версий.

Когда ClickPipes начнет синхронизировать данные с ClickHouse, используйте pg_clickhouse, чтобы быстро и просто import foreign tables в схему PostgreSQL. Затем выполняйте существующие PostgreSQL-запросы к этим таблицам, сохраняя текущую кодовую базу и при этом перенося выполнение в ClickHouse.

​

Начало работы

Самый простой способ опробовать pg_clickhouse — воспользоваться [Docker-образом], который включает стандартный Docker-образ PostgreSQL с расширениями pg_clickhouse и 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'

См. [руководство], чтобы начать импорт таблиц ClickHouse и выполнять запросы с pushdown.

​

Тестовый сценарий: TPC-H

В этой таблице сравнивается производительность запросов TPC-H для обычных таблиц PostgreSQL и pg_clickhouse, подключённого к ClickHouse; в обоих случаях данные загружены с коэффициентом масштабирования 1. ✔︎ означает полный pushdown, а тире обозначает отмену запроса через 1 мин. Все тесты выполнялись на MacBook Pro M4 Max с 36 ГБ памяти.

Запрос	PostgreSQL	pg_clickhouse	Pushdown
[Query 1]	4693 ms	268 ms	✔︎
[Query 2]	458 ms	3446 ms
[Query 3]	742 ms	111 ms	✔︎
[Query 4]	270 ms	130 ms	✔︎
[Query 5]	337 ms	1460 ms	✔︎
[Query 6]	764 ms	53 ms	✔︎
[Query 7]	619 ms	96 ms	✔︎
[Query 8]	342 ms	156 ms	✔︎
[Query 9]	3094 ms	298 ms	✔︎
[Query 10]	581 ms	197 ms	✔︎
[Query 11]	212 ms	24 ms
[Query 12]	1116 ms	84 ms	✔︎
[Query 13]	958 ms	1368 ms
[Query 14]	181 ms	73 ms	✔︎
[Query 15]	1118 ms	557 ms
[Query 16]	497 ms	1714 ms
[Query 17]	1846 ms	32709 ms
[Query 18]	5823 ms	10649 ms
[Query 19]	53 ms	206 ms	✔︎
[Query 20]	421 ms	-
[Query 21]	1349 ms	4434 ms
[Query 22]	258 ms	1415 ms

​

Сборка из исходного кода

​

Unix (общий случай)

Пакеты разработки для PostgreSQL и curl включают pg_config и curl-config в path, поэтому достаточно просто выполнить make (или gmake), затем make install, а затем в своей базе данных CREATE EXTENSION pg_clickhouse.

​

Debian / Ubuntu / APT

Подробности о получении пакетов из репозитория PostgreSQL Apt см. в 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

Подробнее о получении пакетов из репозитория PostgreSQL Yum см. в PostgreSQL Yum.

​

Установка из PGXN

После установки указанных выше зависимостей используйте PGXN client (доступный в виде пакетов Homebrew, Apt и Yum под именем pgxnclient) для загрузки, компиляции и установки pg_clickhouse:

pgxn install pg_clickhouse

​

Сборка и установка

Чтобы собрать и установить библиотеку ClickHouse и pg_clickhouse, выполните:

make
sudo make install

Если на вашем хосте установлено несколько версий PostgreSQL, может потребоваться указать подходящую версию pg_config:

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

Если curl-config отсутствует в переменной PATH на вашем хосте, вы можете указать путь явно:

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

Если вы столкнулись, например, со следующей ошибкой:

"Makefile", line 8: Need an operator

Вам нужно использовать GNU make, который может быть установлен в вашей системе под именем gmake:

gmake
gmake install
gmake installcheck

Если вы столкнулись, например, со следующей ошибкой:

make: pg_config: Command not found

Убедитесь, что pg_config установлен и доступен в вашем path. Если вы устанавливали PostgreSQL с помощью системы управления пакетами, например RPM, убедитесь, что пакет -devel тоже установлен. При необходимости укажите процессу сборки, где его искать:

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

Чтобы установить расширение в пользовательский префикс в PostgreSQL 18 и более поздних версиях, передайте аргумент prefix для install (но не для других целей make):

sudo make install prefix=/usr/local/extras

Затем убедитесь, что префикс указан в следующих параметрах [postgresql.conf]:

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

​

Тестирование

Чтобы запустить набор тестов после установки расширения, выполните

make installcheck

Если вы столкнулись с такой ошибкой:

ERROR:  must be owner of database regression

Вам нужно запустить набор тестов от имени суперпользователя, например суперпользователя “postgres”, используемого по умолчанию:

make installcheck PGUSER=postgres

​

Подключение

После установки pg_clickhouse вы можете подключить его к базе данных, войдя под суперпользователем и выполнив:

CREATE EXTENSION pg_clickhouse;

Если вы хотите установить pg_clickhouse и все связанные с ним объекты в определённую схему, используйте конструкцию SCHEMA, чтобы указать эту схему, например:

CREATE SCHEMA env;
CREATE EXTENSION pg_clickhouse SCHEMA env;

​

Зависимости

Для расширения pg_clickhouse требуются PostgreSQL версии 13 или выше, libcurl и libuuid. Для сборки расширения требуются компиляторы C и C++, libSSL, GNU make и CMake.

​

План развития

Наш главный приоритет — завершить поддержку pushdown для аналитических рабочих нагрузок, прежде чем добавлять возможности DML. Наш план развития:

• Обеспечить оптимальное планирование для оставшихся 10 запросов TPC-H без pushdown
• Протестировать и исправить pushdown для запросов ClickBench
• Поддержать прозрачный pushdown всех агрегатных функций PostgreSQL
• Поддержать прозрачный pushdown всех функций PostgreSQL
• Разрешить настройки ClickHouse на уровне сервера и сеанса через CREATE SERVER и GUC
• Поддержать все типы данных ClickHouse
• Поддержать легковесные DELETE и UPDATE
• Поддержать батч-вставку через COPY
• Добавить функцию для выполнения произвольного запроса к ClickHouse и возврата его результатов в виде таблиц
• Добавить поддержку pushdown для запросов UNION, когда все они обращаются к удалённой базе данных

​

Авторы

• David E. Wheeler
• Ildus Kurbangaliev
• Ibrar Ahmed

​

Авторские права

• Авторские права (c) 2025-2026, ClickHouse
• Авторские права на отдельные части (c) 2023-2025, Ildus Kurbangaliev
• Авторские права на отдельные части (c) 2019-2023, Adjust GmbH
• Авторские права на отдельные части (c) 2012-2019, PostgreSQL Global Development Group

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