pg_clickhouse

Введение

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

Как только ClickPipes начинают синхронизировать данные в ClickHouse, используйте pg_clickhouse, чтобы быстро и просто [импортировать внешние таблицы] в схему PostgreSQL. Затем запускайте ваши существующие PostgreSQL‑запросы по этим таблицам, сохраняя вашу текущую кодовую базу и при этом передавая выполнение запросов в ClickHouse.

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

Самый простой способ попробовать pg_clickhouse — воспользоваться [образом Docker], который содержит стандартный Docker-образ PostgreSQL с расширением pg_clickhouse:

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 и настроить проталкивание запросов.

Тестовый пример: TPC-H

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

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

Red Hat / 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. Если вы использовали систему управления пакетами, такую как RPM, для установки PostgreSQL, убедитесь, что пакет -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 parameters:

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

Авторы

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

Введение​

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

Тестовый пример: TPC-H​

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

Общий Unix​

Debian / Ubuntu / APT​

Red Hat / CentOS / Yum​

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

Компиляция и установка​

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

Загрузка​

Зависимости​

Дорожная карта​

Авторы​

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