Подключение к кластеру ClickHouse® из приложений

Статья создана

Обновлена 26 сентября 2025 г.

Инструменты командной строки
Подключение из графических IDE
- DataGrip
- DBeaver
Подключение из браузера
- Консоль управления Yandex Cloud
- Встроенный SQL-редактор ClickHouse®
Подготовка к подключению из Docker-контейнера

В этом разделе представлены настройки для подключения к хостам кластера Managed Service for ClickHouse® с помощью инструментов командной строки, из графических IDE, браузера и Docker-контейнера. О подключении из кода вашего приложения см. Примеры кода.

Вы можете подключаться к хостам кластера ClickHouse® в публичном доступе только с использованием SSL-сертификатов. В примерах ниже предполагается, что сертификаты RootCA.crt и IntermediateCA.crt:

расположены в директории /usr/local/share/ca-certificates/Yandex/ — для Ubuntu;
импортированы в хранилище доверенных корневых сертификатов — для Windows.

Подключение без использования SSL-сертификатов поддерживается только для хостов, находящихся не в публичном доступе. В этом случае трафик внутри виртуальной сети при подключении к БД шифроваться не будет.

При необходимости перед подключением настройте группы безопасности кластера.

Примеры для Linux проверялись в следующем окружении:

Виртуальная машина в Yandex Cloud с Ubuntu 20.04 LTS.
Bash: 5.0.16.

Примеры для Windows проверялись в следующем окружении:

Локальная машина с Windows 10 Pro build 19042.1052.
PowerShell: 5.1.19041.

Инструменты командной строки

Примеры кода с заполненным FQDN хоста доступны в консоли управления по нажатию кнопки Подключиться на странице кластера.

clickhouse-client

Перед подключением:

Подключите DEB-репозиторий ClickHouse®:

sudo apt update && sudo apt install --yes apt-transport-https ca-certificates dirmngr && \
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754 && \
echo "deb https://packages.clickhouse.com/deb stable main" | sudo tee \
/etc/apt/sources.list.d/clickhouse.list

Установите зависимости:

sudo apt update && sudo apt install --yes clickhouse-client

Загрузите файл конфигурации для clickhouse-client:

mkdir -p ~/.clickhouse-client && \
wget "https://storage.yandexcloud.net/doc-files/clickhouse-client.conf.example" \
  --output-document ~/.clickhouse-client/config.xml

Подключение без SSL

Подключение с SSL

clickhouse-client --host <FQDN_любого_хоста_ClickHouse®> \
                  --user <имя_пользователя> \
                  --database <имя_БД> \
                  --port 9000 \
                  --ask-password

clickhouse-client --host <FQDN_любого_хоста_ClickHouse®> \
                  --secure \
                  --user <имя_пользователя> \
                  --database <имя_БД> \
                  --port 9440 \
                  --ask-password

О том, как получить FQDN хоста, см. инструкцию.

После выполнения команды введите пароль пользователя для завершения процедуры подключения.

После подключения к СУБД выполните команду SELECT version();.

mysql-client

Важно

Используйте интерфейс подключения через клиент MySQL® только если использование стандартных интерфейсов ClickHouse® по каким-либо причинам невозможно.

Перед подключением установите утилиту mysql:

sudo apt update && sudo apt install --yes mysql-client

Подключение без SSL

Подключение с SSL

mysql --host=<FQDN_любого_хоста_ClickHouse®> \
      --port=3306 \
      --ssl-mode=DISABLED \
      --user <имя_пользователя> \
      --password \
      <имя_БД>

mysql --host=<FQDN_любого_хоста_ClickHouse®> \
      --port=3306 \
      --ssl-ca=/usr/local/share/ca-certificates/Yandex/RootCA.crt \
      --ssl-mode=VERIFY_IDENTITY \
      --user=<имя_пользователя> \
      --password \
      <имя_БД>

О том, как получить FQDN хоста, см. инструкцию.

После выполнения команды введите пароль пользователя для завершения процедуры подключения.

После подключения к СУБД выполните команду SELECT version();.

cURL

Linux (Bash)/macOS (Zsh)

Подключение без SSL

Подключение с SSL

curl --header "X-ClickHouse-User: <имя_пользователя_БД>" \
     --header "X-ClickHouse-Key: <пароль_пользователя_БД>" \
     'http://<FQDN_любого_хоста_ClickHouse®>:8123/?database=<имя_БД>&query=SELECT%20version()'

curl --cacert /usr/local/share/ca-certificates/Yandex/RootCA.crt \
     --header "X-ClickHouse-User: <имя_пользователя_БД>" \
     --header "X-ClickHouse-Key: <пароль_пользователя_БД>" \
     'https://<FQDN_любого_хоста_ClickHouse®>:8443/?database=<имя_БД>&query=SELECT%20version()'

О том, как получить FQDN хоста, см. инструкцию.

Windows (PowerShell)

Подключение без SSL

Подключение с SSL

curl.exe `
    --header "X-ClickHouse-User: <имя_пользователя_БД>" `
    --header "X-ClickHouse-Key: <пароль_пользователя_БД>" `
    'http://<FQDN_любого_хоста_ClickHouse®>:8123/?database=<имя_БД>&query=SELECT+version()'

curl.exe `
    --header "X-ClickHouse-User: <имя_пользователя_БД>" `
    --header "X-ClickHouse-Key: <пароль_пользователя_БД>" `
    'https://<FQDN_любого_хоста_ClickHouse®>:8443/?database=<имя_БД>&query=SELECT+version()'

О том, как получить FQDN хоста, см. инструкцию.

Подключение из графических IDE

Подключения проверялись в следующем окружении:

Ubuntu 20.04, DBeaver: 22.2.4;
MacOS Monterey 12.7:
- JetBrains DataGrip: 2023.3.4;
- DBeaver Community: 24.0.0.

Подключаться из графических IDE можно только к хостам кластера в публичном доступе с использованием SSL-сертификата.

Чтобы избежать ошибок при подключении, сохраните сертификат в локальную папку, для доступа к которой не требуются права администратора.

DataGrip

Создайте источник данных:
1. Выберите в меню File → New → Data Source → ClickHouse®.
2. На вкладке General:
  1. Укажите параметры подключения:
    - Host — FQDN любого хоста ClickHouse® или один из особых FQDN;
    - Port — 8443;
    - User, Password — имя и пароль пользователя БД;
    - Database — имя БД для подключения.
  2. Нажмите ссылку Download, чтобы загрузить драйвер соединения.
3. На вкладке SSH/SSL:
  1. Включите настройку Use SSL.
  2. Укажите папку с файлом скачанного SSL-сертификата для подключения.
Нажмите ссылку Test Connection для проверки подключения. При успешном подключении будет выведен статус подключения, информация о СУБД и драйвере.
Нажмите кнопку OK, чтобы сохранить источник данных.

DBeaver

Создайте новое соединение с БД:
1. Выберите в меню База данных пункт Новое соединение.
2. Выберите из списка БД ClickHouse®.
3. Нажмите кнопку Далее.
4. Укажите параметры подключения на вкладке Главное:
  - Хост — FQDN любого хоста ClickHouse® или один из особых FQDN;
  - Порт — 8443;
  - БД/Схема — имя БД для подключения;
  - В блоке Аутентификация укажите имя и пароль пользователя БД.
5. На вкладке Свойства драйвера:
  1. Нажмите Скачать в новом окне с приглашением скачать файлы драйвера.
  2. Укажите параметры для SSL-соединения в списке свойств драйвера:
    - ssl:true;
    - sslrootcert:<путь_к_сохраненному_файлу_SSL-сертификата>.
Нажмите кнопку Тест соединения ... для проверки подключения. При успешном подключении будет выведен статус подключения, информация о СУБД и драйвере.
Нажмите кнопку Готово, чтобы сохранить настройки соединения с БД.

Подключение из браузера

Для выполнения SQL-запросов из браузера используйте:

При подключении из браузера SQL-запросы выполняются отдельно, без создания единой сессии с сервером ClickHouse®. Поэтому запросы, которые действуют в пределах сессии (например, USE или SET), не имеют эффекта.

Консоль управления Yandex Cloud

Чтобы подключиться к кластеру Managed Service for ClickHouse®, войдите в консоль управления, откройте страницу нужного кластера и перейдите на вкладку SQL.

Для разрешения подключения включите опцию Доступ из консоли управления при создании кластера или изменении его настроек.

Подробнее см. в разделе SQL-запросы.

Встроенный SQL-редактор ClickHouse®

Чтобы подключиться к хосту кластера из встроенного SQL-редактора, укажите в браузере адресную строку:

https://<FQDN_любого_хоста_ClickHouse®>:8443/play

Подключаться можно только к хостам кластера в публичном доступе. О том, как получить FQDN хоста, см. инструкцию.

Чтобы подключиться к кластеру с помощью автоматического выбора доступного хоста, используйте адрес:

https://c-<идентификатор_кластера>.rw.mdb.yandexcloud.kz:8443/play — для подключения к доступному хосту кластера.
https://<имя_шарда>.c-<идентификатор_кластера>.rw.mdb.yandexcloud.kz:8443/play — для подключения к доступному хосту шарда.

Для выполнения запросов к базе данных укажите имя пользователя и пароль в правом верхнем углу страницы.

Подготовка к подключению из Docker-контейнера

Чтобы подключаться к кластеру Managed Service for ClickHouse® из Docker-контейнера, добавьте в Dockerfile строки:

Подключение без SSL

Подключение с SSL

# Подключить DEB-репозиторий.
RUN apt-get update && \
    apt-get install wget --yes apt-transport-https ca-certificates dirmngr && \
    apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754 && \
    echo "deb https://packages.clickhouse.com/deb stable main" | tee \
    /etc/apt/sources.list.d/clickhouse.list && \
    # Установить зависимости.
    apt-get update && \
    apt-get install wget clickhouse-client --yes && \
    # Загрузить файл конфигурации для clickhouse-client.
    mkdir --parents ~/.clickhouse-client && \
    wget "https://storage.yandexcloud.net/doc-files/clickhouse-client.conf.example" \
         --output-document ~/.clickhouse-client/config.xml

# Подключить DEB-репозиторий.
RUN apt-get update && \
    apt-get install wget --yes apt-transport-https ca-certificates dirmngr && \
    apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754 && \
    echo "deb https://packages.clickhouse.com/deb stable main" | tee \
    /etc/apt/sources.list.d/clickhouse.list && \
    # Установить зависимости.
    apt-get update && \
    apt-get install wget clickhouse-client --yes && \
    # Загрузить файл конфигурации для clickhouse-client.
    mkdir --parents ~/.clickhouse-client && \
    wget "https://storage.yandexcloud.net/doc-files/clickhouse-client.conf.example" \
         --output-document ~/.clickhouse-client/config.xml && \
    # Получить SSL-сертификаты.
    mkdir --parents /usr/local/share/ca-certificates/Yandex/ && \
    wget "https://storage.yandexcloud.kz/cloud-certs/RootCA.pem" \
         --output-document /usr/local/share/ca-certificates/Yandex/RootCA.crt && \
    wget "https://storage.yandexcloud.kz/cloud-certs/IntermediateCA.pem" \
         --output-document /usr/local/share/ca-certificates/Yandex/IntermediateCA.crt && \
    chmod 655 \
         /usr/local/share/ca-certificates/Yandex/RootCA.crt \
         /usr/local/share/ca-certificates/Yandex/IntermediateCA.crt && \
    update-ca-certificates

ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc.

Подключение к кластеру ClickHouse® из приложений

Инструменты командной строкиИнструменты командной строки

clickhouse-clientclickhouse-client

mysql-clientmysql-client

cURLcURL

Linux (Bash)/macOS (Zsh)Linux (Bash)/macOS (Zsh)

Windows (PowerShell)Windows (PowerShell)

Подключение из графических IDEПодключение из графических IDE

DataGripDataGrip

DBeaverDBeaver

Подключение из браузераПодключение из браузера

Консоль управления Yandex CloudКонсоль управления Yandex Cloud

Встроенный SQL-редактор ClickHouse®Встроенный SQL-редактор ClickHouse®

Подготовка к подключению из Docker-контейнераПодготовка к подключению из Docker-контейнера

Была ли статья полезна?

Инструменты командной строки

clickhouse-client

mysql-client

cURL

Linux (Bash)/macOS (Zsh)

Windows (PowerShell)

Подключение из графических IDE

DataGrip

DBeaver

Подключение из браузера

Консоль управления Yandex Cloud

Встроенный SQL-редактор ClickHouse®

Подготовка к подключению из Docker-контейнера