Skip to main content

Введение

Эта библиотека предоставляет расширения PostgreSQL для выполнения запросов chDB в Postgres, а также для копирования данных в различные форматы и объектные хранилища и обратно.

Расширение chDB

Расширение chdb выполняет запросы chDB. Функция chdb_query() выполняет один запрос. Например, следующий запрос:
Output:
Подробнее см. в документации chDB.

Модуль chdb_hook

Модуль chdb_hook встраивается в команду COPY, позволяя копировать данные в S3, GCS, Azure Blob, файл или http URL, а также из них. В этом примере записи загружаются из нескольких CSV-файлов в S3 одной командой COPY:
После этого таблица times содержит записи из каждого загруженного файла:
Команда CREATE TABLE также может вывести свои столбцы и загрузить строки из такого URL:
Подробнее см. в документации chdb_hook.

Бенчмаркинг форматов

Бенчмарк сравнивает производительность COPY в [chDB_hook] с производительностью [aws_s3], [pg_duckdb] и [pg_lake] примерно на 1 млн строк NYC Taxi dataset в различных форматах. Бенчмарк данных NYC Taxi Из этих четырёх расширений chDB демонстрирует наиболее стабильную производительность. [pg_duckdb] и [pg_lake], оба построенные на DuckDB, тратят примерно в 2–3 раза больше времени на импорт данных из CSV, JSON и Parquet. Только [aws_s3] приближается к производительности [chDB_hook], но он поддерживает существенно более ограниченный набор форматов данных: Дополнительные измерения показывают относительно стабильную производительность при импорте NYC Taxi dataset в различных форматах: Бенчмарк импорта В бенчмарке используется формат JSONCompact — ради совместимости с другими расширениями; прочие форматы JSON, например JSONCompactEachRow, будут ближе по производительности к остальным форматам.

Архитектура

Расширения chDB и chDB_hook используют процесс chdb_helper для выполнения запросов chDB. Вспомогательный процесс отделяет потребление ресурсов chDB от основного процесса Postgres, что даёт преимущество для нерегулярно выполняемых сценариев, таких как загрузка данных из озера данных.
В отличие от background worker, вспомогательный процесс не занимает разделяемую память Postgres, и postmaster им не управляет. Благодаря этому сбои изолированы и не влияют на Postgres. Аварийное завершение вспомогательного процесса приводит к ошибке только в том backend-соединении, которое его запустило, не затрагивая остальные сеансы.

Зависимости

Расширению chdb требуется PostgreSQL 15 или выше и библиотека chDB версии 26.7.0 или выше (в настоящее время доступна только для Linux и macOS). Проще всего установить её с помощью shell-скрипта lib.chdb.io:
Чтобы статически скомпилировать chDB во вспомогательное приложение, задайте следующие переменные перед выполнением команд make из раздела Установка.
Makefile загрузит статическую библиотеку libchdb и встроит её в приложение при компиляции. В Linux можно также сделать так, чтобы в процессе установки загружалась и устанавливалась динамическая библиотека libchdb — для этого задайте export BUNDLE_LIBCHDB=1 перед выполнением команд make из раздела Установка.

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

Чтобы собрать chDB, достаточно выполнить следующее:
Если вы столкнётесь с ошибкой вида:
Вам потребуется GNU make, который в вашей системе вполне может быть установлен под именем gmake:
Если вы столкнулись с ошибкой вида:
Убедитесь, что pg_config установлен и доступен в переменной path. Если PostgreSQL был установлен с помощью системы управления пакетами, например RPM, убедитесь, что установлен также пакет -devel. При необходимости укажите процессу сборки, где его искать:
Если вы столкнулись с ошибкой вида:
Вам нужно либо установить chDB, либо указать компилятору, где его найти. Например, если вы установили его с помощью shell-скрипта lib.chdb.io, укажите путь /usr/local:
Если вы столкнулись с ошибкой вида:
Набор тестов необходимо запускать от имени суперпользователя, например стандартного суперпользователя “postgres”:
Чтобы установить расширение в custom prefix на PostgreSQL 18 или более поздней версии, передайте argument prefix цели install (но не другим целям make):
Затем убедитесь, что этот префикс указан в следующих [параметрах postgresql.conf]:

Авторы

Copyright (c) 2026, ClickHouse
Последнее изменение 26 сентября 2026 г.