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

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

Yandex Cloud

Улучшена

Обновлена 30 октября 2026 г.

Открыть в Markdown

Инструменты командной строки
Подключение из графических IDE
Подключение из браузера
- Консоль управления 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 хоста, описано в инструкции.

Подключение с аутентификацией через IAM

К базе данных ClickHouse® можно подключиться с помощью интерфейса командной строки Yandex Cloud (CLI) или clickhouse-client, используя аутентификацию через IAM. Этот метод доступен для аккаунтов на Яндексе, федеративных аккаунтов или локальных пользователей.

Чтобы подключиться к БД ClickHouse® с аутентификацией через IAM:

Установите и настройте клиент ClickHouse®.
Для доступа к кластеру назначьте роль managed-clickhouse.clusters.connector аккаунту пользователя, который будет подключаться к БД. Если вы хотите настроить подключение к кластеру через сервисный аккаунт, дополнительно назначьте роль iam.serviceAccounts.user.
Создайте пользователя ClickHouse® с аутентификацией через IAM и укажите аккаунт, которому была назначена роль managed-clickhouse.clusters.connector.
Подключитесь к БД ClickHouse®:
CLI

clickhouse-client
1. Для доступа к кластеру дополнительно назначьте роль managed-clickhouse.viewer аккаунту пользователя, который будет подключаться к БД.
2. Выполните команду:
  yc managed-clickhouse connect <имя_или_идентификатор_кластера> --db <имя_БД>
Подключение этим способом не требует указания FQDN хостов кластера.
1. Получите IAM-токен для аккаунта, которому ранее был выдан доступ к кластеру.
2. Выполните команду:
  - Для подключения без SSL:
    
    clickhouse-client --host <FQDN_любого_хоста_ClickHouse®> \ --user <идентификатор_аккаунта_или_электронная_почта> \ --database <имя_БД> \ --port 9000 \ --ask-password
  - Для подключения с SSL:
    
    clickhouse-client --host <FQDN_любого_хоста_ClickHouse®> \ --secure \ --user <идентификатор_аккаунта_или_электронная_почта> \ --database <имя_БД> \ --port 9440 \ --ask-password
  В качестве имени пользователя укажите идентификатор аккаунта или электронную почту пользователя, к которой привязан аккаунт, а в качестве пароля — полученный IAM-токен.
  
  Как получить 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-сертификата.

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

Совет

Вы можете подключаться из графических IDE с помощью аутентификации через IAM. Для этого:

Настройте подключение.
Получите IAM-токен для аккаунта, которому было настроено подключение через IAM.
При подключении укажите в качестве имени пользователя идентификатор аккаунта, а в качестве пароля — полученный IAM-токен.

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-сертификата_включая_имя_файла>.
Нажмите кнопку Тест соединения ... для проверки подключения. При успешном подключении будет выведен статус подключения, информация о СУБД и драйвере.
Нажмите кнопку Готово, чтобы сохранить настройки соединения с БД.

Подключение с аутентификацией через IAM

Подключение доступно для аккаунтов Yandex Cloud и не требует указания FQDN хостов кластера.

Чтобы подключиться к БД ClickHouse®:

Для доступа к кластеру назначьте роль managed-clickhouse.clusters.connector аккаунту пользователя, который будет подключаться к БД.
Создайте пользователя ClickHouse® с аутентификацией через IAM и укажите аккаунт, которому была назначена роль managed-clickhouse.clusters.connector.
Получите IAM-токен для аккаунта, которому было настроено подключение через IAM.
При подключении в DataGrip или DBeaver укажите в качестве имени пользователя идентификатор аккаунта или электронную почту пользователя, к которой привязан аккаунт, а в качестве пароля — полученный IAM-токен.

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

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

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

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

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

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

Подробнее в разделе 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 && \
    chmod 655 \
         /usr/local/share/ca-certificates/Yandex/RootCA.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)

Подключение с аутентификацией через IAMПодключение с аутентификацией через IAM

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

DataGripDataGrip

DBeaverDBeaver

Подключение с аутентификацией через IAMПодключение с аутентификацией через IAM

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

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

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

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

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

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

clickhouse-client

mysql-client

cURL

Linux (Bash)/macOS (Zsh)

Windows (PowerShell)

Подключение с аутентификацией через IAM

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

DataGrip

DBeaver

Подключение с аутентификацией через IAM

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

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

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

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