> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Выполняйте аналитические запросы в ClickHouse прямо из PostgreSQL без переписывания SQL # Справочник по pg_clickhouse
## Введение
\[pg\_clickhouse] — расширение PostgreSQL с открытым исходным кодом, которое позволяет выполнять аналитические запросы в ClickHouse прямо из PostgreSQL без какого-либо переписывания SQL. Оно поддерживает PostgreSQL 13 и более поздние версии, а также ClickHouse v23 и выше. Когда [ClickPipes](/ru/integrations/clickpipes/home) начнет синхронизировать данные с ClickHouse, используйте pg\_clickhouse, чтобы быстро и просто выполнить [import foreign tables] в схему PostgreSQL. Затем запускайте существующие запросы PostgreSQL к этим таблицам, сохраняя текущую кодовую базу и передавая выполнение в ClickHouse.
## Начало работы
Самый простой способ попробовать pg\_clickhouse — воспользоваться \[Docker-образом], который содержит стандартный Docker-образ PostgreSQL с расширениями pg\_clickhouse и [re2]: ```sh theme={null} 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 и перенос выполнения запросов в ClickHouse.
## Тестовый пример: TPC-H
В этой таблице сравнивается производительность запросов [TPC-H] для обычных таблиц PostgreSQL и pg\_clickhouse, подключенного к ClickHouse; оба варианта загружены при коэффициенте масштабирования 1. ✔︎ означает полный pushdown, а тире — отмену запроса через 1 мин. Все тесты выполнялись на MacBook Pro M4 Max с 36 ГБ памяти. | Query | 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` в путь, поэтому вы можете просто выполнить `make` (или `gmake`), затем `make install`, а затем в своей базе данных `CREATE EXTENSION pg_clickhouse`.
#### Debian / Ubuntu / APT
См. [PostgreSQL Apt], чтобы узнать подробности о получении пакетов из репозитория PostgreSQL Apt. ```sh theme={null} sudo apt install \ postgresql-server-18 \ libcurl4-openssl-dev \ uuid-dev \ libssl-dev \ make \ cmake \ g++ ```
#### RedHat / CentOS / Yum
```sh theme={null} 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`: ```sh theme={null} pgxn install pg_clickhouse ```
#### Сборка и установка
Чтобы собрать и установить библиотеку ClickHouse и `pg_clickhouse`, выполните: ```sh theme={null} make sudo make install ``` Если на вашем хосте установлено несколько версий PostgreSQL, может потребоваться указать подходящую версию `pg_config`: ```sh theme={null} export PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config make sudo make install ``` Если `curl-config` не находится в PATH на вашем хосте, вы можете явно указать путь: ```sh theme={null} export CURL_CONFIG=/opt/homebrew/opt/curl/bin/curl-config make sudo make install ``` Если вы столкнулись с ошибкой, например: ```text theme={null} "Makefile", line 8: Need an operator ``` Вам нужно использовать GNU make; в вашей системе он вполне может быть установлен как `gmake`: ```sh theme={null} gmake gmake install gmake installcheck ``` Если вы столкнулись с ошибкой, например: ```text theme={null} make: pg_config: Command not found ``` Убедитесь, что `pg_config` установлен и доступен в переменной path. Если вы использовали для установки PostgreSQL систему управления пакетами, например RPM, убедитесь, что пакет `-devel` тоже установлен. При необходимости укажите процессу сборки, где его найти: ```sh theme={null} export PG_CONFIG=/path/to/pg_config make sudo make install ``` Чтобы установить расширение в пользовательский префикс в PostgreSQL 18 или более поздней версии, передайте аргумент `prefix` команде `install` (но не другим целям `make`): ```sh theme={null} sudo make install prefix=/usr/local/extras ``` Затем убедитесь, что префикс указан в следующих \[параметрах `postgresql.conf`]: ```ini theme={null} extension_control_path = '/usr/local/extras/postgresql/share:$system' dynamic_library_path = '/usr/local/extras/postgresql/lib:$libdir' ```
#### Тестирование
Чтобы запустить набор тестов после установки расширения, выполните ```sh theme={null} make installcheck ``` Если вы столкнулись, например, с такой ошибкой: ```text theme={null} ERROR: must be owner of database regression ``` Вам нужно запустить набор тестов от имени суперпользователя, например стандартного суперпользователя "postgres": ```sh theme={null} make installcheck PGUSER=postgres ```
### Подключение
После установки `pg_clickhouse` его можно подключить к базе данных, подключившись под суперпользователем и выполнив: ```sql theme={null} CREATE EXTENSION pg_clickhouse; ``` Если вы хотите установить `pg_clickhouse` и все связанные с ним объекты в конкретную схему, используйте предложение `SCHEMA` для указания схемы, например: ```sql theme={null} 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](https://justatheory.com/) * [Ildus Kurbangaliev](https://github.com/ildus) * [Ibrar Ahmed](https://github.com/ibrarahmad) * Авторские права (c) 2025-2026, ClickHouse * Отдельные части: авторские права (c) 2023-2025, Ildus Kurbangaliev * Отдельные части: авторские права (c) 2019-2023, Adjust GmbH * Отдельные части: авторские права (c) 2012-2019, PostgreSQL Global Development Group [pg_clickhouse]: https://github.com/clickHouse/pg_clickhouse "pg_clickhouse на GitHub" [import foreign tables]: /products/managed-postgres/extensions/pg_clickhouse/reference#import-foreign-schema [Docker image]: https://github.com/ClickHouse/pg_clickhouse/pkgs/container/pg_clickhouse "Последний релиз Docker-образа" [tutorial]: /products/managed-postgres/extensions/pg_clickhouse/tutorial "Руководство по pg_clickhouse" [PostgreSQL Apt]: https://wiki.postgresql.org/wiki/Apt [PostgreSQL Yum]: https://yum.postgresql.org [PGXN client]: https://pgxn.github.io/pgxnclient/ "Документация клиента PGXN" [Homebrew]: https://formulae.brew.sh/formula/pgxnclient#default "PGXN client в Homebrew" [Apt]: https://tracker.debian.org/pkg/pgxnclient "PGXN client в Debian Apt" [`postgresql.conf` parameters]: https://www.postgresql.org/docs/devel/runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER [PostgreSQL]: https://www.postgresql.org "PostgreSQL: самая продвинутая в мире реляционная база данных с открытым исходным кодом" [libcurl]: https://curl.se/libcurl/ "libcurl — библиотека для передачи данных по сети" [libuuid]: https://linux.die.net/man/3/libuuid "libuuid — DCE-совместимая библиотека универсальных уникальных идентификаторов" [GNU make]: https://www.gnu.org/software/make "GNU Make" [CMake]: https://cmake.org/ "CMake: мощная система сборки программного обеспечения" [LibSSL]: https://openssl-library.org "Библиотека OpenSSL" [TPC-H]: https://www.tpc.org/tpch/ [re2]: https://github.com/ClickHouse/pg_re2 "pg_re2: совместимые с ClickHouse функции регулярных выражений на базе RE2" \[Запрос 1] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/1.sql](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/22.sql)