Связаться с намиПодключиться

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

Статья создана
Обновлена 7 ноября 2025 г.

В этом разделе представлены настройки для подключения к хостам кластера 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

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

  1. Подключите 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

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

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

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

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

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

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)

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)

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. Создайте источник данных:
    1. Выберите в меню File → New → Data Source → ClickHouse®.
    2. На вкладке General:
      1. Укажите параметры подключения:
      2. Нажмите ссылку Download, чтобы загрузить драйвер соединения.
    3. На вкладке SSH/SSL:
      1. Включите настройку Use SSL.
      2. Укажите папку с файлом скачанного SSL-сертификата для подключения.
  2. Нажмите ссылку Test Connection для проверки подключения. При успешном подключении будет выведен статус подключения, информация о СУБД и драйвере.
  3. Нажмите кнопку OK, чтобы сохранить источник данных.

DBeaver

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

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

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

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

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

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

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

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

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

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

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

Сервис Yandex WebSQL

Примечание

Функциональность находится на стадии Preview.

Используйте сервис Yandex WebSQL для подключения к кластеру ClickHouse® в Yandex Cloud.

Перед созданием подключения убедитесь, что вы выбрали нужный каталог. Если у вас есть доступ к ранее созданным в этом каталоге кластерам PostgreSQL, ClickHouse®, MySQL®, Greenplum®, Valkey™ или Yandex StoreDoc, они автоматически отобразятся в подразделе Подключения Yandex Cloud. Вам нужно будет только создать подключение к нужной БД в кластере.

Примечание

Yandex Managed Service for Trino находится на стадии Preview. В интерфейсе Yandex WebSQL пока нельзя создавать подключения к Yandex Managed Service for Trino, но если в текущем каталоге есть кластер Yandex Managed Service for Trino и у пользователя есть к нему доступ, подключение отобразится в WebSQL и будет доступно для использования.

WebSQL использует подключения в Connection Manager сервиса Yandex MetaData Hub, поэтому все подключения, настроенные в Connection Manager, доступны для работы в WebSQL автоматически при условии, что у пользователя есть роли.

Чтобы создать подключение к кластеру управляемых БД Yandex Cloud:

  1. Убедитесь, что в настройках кластера включена опция Доступ из WebSQL.
  2. Откройте Подключения Yandex WebSQL.
  3. В разделе Подключения нажмите .
  4. В поле Тип базы данных выберите нужную БД: PostgreSQL, ClickHouse®, MySQL®, Valkey™, Yandex StoreDoc, Greenplum®.
  5. В поле Каталог кластера выберите каталог, в котором содержится нужный кластер.
  6. В поле Кластер выберите кластер управляемых БД, к которому вы хотите подключиться.
  7. Укажите Имя пользователя, от лица которого будете подключаться к БД в кластере.
  8. Введите Пароль пользователя.
  9. Перечислите Базы данных, к которым вы хотите подключиться. Вы можете подключиться только к существующим в этом кластере БД. У пользователя, которого вы указали, должен быть настроен доступ к ним.
  10. Нажмите кнопку Создать.

Для формирования запроса:

  1. В разделе Подключения выберите базу данных, таблицу или представление.

  2. На панели данных появится форма с запросом по умолчанию:

    SELECT * FROM <имя_таблицы> LIMIT 10;

  3. Используйте этот запрос или измените его. Интерфейс подскажет вам возможные части запроса и подсветит ошибки.

  4. Нажмите кнопку Выполнить.

На панели результатов появится таблица с результатами запроса.

При редактировании и выполнении запроса вы можете использовать комбинации горячих клавиш (нажмите для просмотра полного списка):

  • показать подсказки: Ctrl + I , Ctrl + Space;
  • закомментировать строку: Ctrl + /;
  • выполнить запрос: Ctrl + Enter.
  • показать подсказки: ⌘ + I , ⌃ + Space;
  • закомментировать строку: ⌘ + /;
  • выполнить запрос: ⌘ + ⏎.

Нажмите Открыть палитру команд, чтобы просмотреть полный список доступных команд и соответствующих им горячих клавиш.

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

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

# Подключить 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.net/cloud-certs/RootCA.pem" \
         --output-document /usr/local/share/ca-certificates/Yandex/RootCA.crt && \
    wget "https://storage.yandexcloud.net/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.

Предыдущая
FQDN хостов
Следующая
Примеры кода