Перейти к основному содержанию
Перейти к основному содержанию

ODBC-драйвер

ODBC-драйвер ClickHouse предоставляет интерфейс, соответствующий стандартам, для подключения ODBC-совместимых приложений к ClickHouse. Он реализует ODBC API и позволяет приложениям, BI-инструментам и скриптовым средам выполнять SQL-запросы, получать результаты и взаимодействовать с ClickHouse через привычные механизмы.

Драйвер обменивается данными с сервером ClickHouse с использованием HTTP-протокола, который является основным протоколом, поддерживаемым во всех развертываниях ClickHouse. Это позволяет драйверу работать единообразно в различных окружениях, включая локальные установки, управляемые облачные сервисы и среды, где доступ возможен только по HTTP.

Исходный код драйвера доступен в ClickHouse-ODBC GitHub Repository.

Совет

Для лучшей совместимости настоятельно рекомендуется обновить сервер ClickHouse до версии 24.11 или более новой.

Примечание

Этот драйвер находится в активной разработке. Некоторые возможности ODBC могут быть ещё не полностью реализованы. Текущая версия сфокусирована на предоставлении базового подключения и основной функциональности ODBC, при этом дополнительные возможности запланированы для будущих релизов.

Ваши отзывы чрезвычайно ценны и помогают определять приоритеты новых возможностей и улучшений. Если вы сталкиваетесь с ограничениями, отсутствующей функциональностью или неожиданным поведением, пожалуйста, поделитесь своими наблюдениями или запросами на новые возможности через трекер задач по адресу https://github.com/ClickHouse/clickhouse-odbc/issues

Установка на Windows​

Последнюю версию драйвера можно найти по адресу https://github.com/ClickHouse/clickhouse-odbc/releases/latest. Там вы можете скачать и запустить установщик MSI и выполнить простые шаги установки.

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

Вы можете протестировать драйвер, запустив этот простой скрипт PowerShell. Скопируйте приведённый ниже текст, укажите URL, пользователя и пароль, затем вставьте текст в командную строку PowerShell — после выполнения $reader.GetValue(0) должна отобразиться версия сервера ClickHouse.

$url = "http://127.0.0.1:8123/"
$user = "default"
$password = ""
$conn = New-Object System.Data.Odbc.OdbcConnection("`
    Driver={ClickHouse ODBC Driver (Unicode)};`
    Url=$url;`
    Username=$username;`
    Password=$password")
$conn.Open()
$cmd = $conn.CreateCommand()
$cmd.CommandText = "select version()"
$reader = $cmd.ExecuteReader()
$reader.Read()
$reader.GetValue(0)
$reader.Close()
$conn.Close()

Параметры конфигурации​

Приведённые ниже параметры представляют собой наиболее часто используемые настройки для настройки соединения через драйвер ClickHouse ODBC. Они охватывают основные параметры аутентификации, поведения соединения и обработки данных. Полный список поддерживаемых параметров доступен на странице проекта в GitHub https://github.com/ClickHouse/clickhouse-odbc.

  • Url: Указывает полный HTTP(S)‑эндпоинт сервера ClickHouse. Включает протокол, хост, порт и необязательный путь.
  • Username: Имя пользователя, используемое для аутентификации на сервере ClickHouse.
  • Password: Пароль, связанный с указанным именем пользователя. Если не задан, драйвер подключается без аутентификации по паролю.
  • Database: База данных по умолчанию, используемая для соединения.
  • Timeout: Максимальное время (в секундах), в течение которого драйвер ожидает ответ сервера перед прерыванием запроса.
  • ClientName: Пользовательский идентификатор, отправляемый на сервер ClickHouse как часть клиентских метаданных. Полезен для трассировки или различения трафика от разных приложений. Этот параметр будет частью заголовка User-Agent в HTTP‑запросах, формируемых драйвером.
  • Compression: Включает или отключает HTTP‑сжатие для полезной нагрузки запросов и ответов. При включении позволяет уменьшить использование полосы пропускания и улучшить производительность для больших наборов результатов.

Ниже приведены примеры полной строки подключения, передаваемой драйверу для установки соединения.

  • Локально установленный сервер ClickHouse в экземпляре WSL
Driver={ClickHouse ODBC Driver (Unicode)};Url=http://localhost:8123//;Username=default
  • Инстанс ClickHouse Cloud.
Driver={ClickHouse ODBC Driver (Unicode)};Url=https://you-instance-url.gcp.clickhouse.cloud:8443/;Username=default;Password=your-password

Интеграция с Microsoft Power BI​

Вы можете использовать ODBC-драйвер для подключения Microsoft Power BI к серверу ClickHouse. Power BI предоставляет два варианта подключения: общий ODBC-коннектор и коннектор ClickHouse, оба входят в стандартную установку Power BI.

Оба коннектора используют ODBC во внутренней реализации, но отличаются возможностями:

  • ClickHouse Connector (рекомендуется)
    Использует ODBC «под капотом», но поддерживает режим DirectQuery. В этом режиме Power BI автоматически генерирует SQL-запросы и получает только те данные, которые необходимы для каждой визуализации или операции фильтрации.

  • ODBC Connector
    Поддерживает только режим Import. Power BI выполняет предоставленный пользователем запрос (или выбирает всю таблицу) и импортирует результирующий набор данных в Power BI. Последующие обновления повторно импортируют весь набор данных.

Выберите коннектор в зависимости от сценария использования: DirectQuery — для интерактивных дашбордов с большими наборами данных, режим Import — когда вам нужны полные локальные копии данных.

Для получения дополнительной информации об интеграции Microsoft Power BI с ClickHouse см. страницу документации ClickHouse по интеграции с Power BI.