Справочник по pg_clickhouse

Введение

[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:19
docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhouse'

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

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

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

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

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

Unix в общем

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

Debian / Ubuntu / APT

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

Подробнее о загрузке из репозитория 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, если все они обращаются к удалённой базе данных

Авторы

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

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