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

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

Обновлена 8 октября 2024 г.

Инструменты командной строки
- clickhouse-client
- cURL
Подключение из графических IDE
- DataGrip
- DBeaver
Подключение из браузера
- Встроенный SQL-редактор ClickHouse®
- Сервис Yandex WebSQL
Подготовка к подключению из 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();.

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®

Чтобы подключиться к хосту кластера из встроенного 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® или Redis, они автоматически отобразятся в подразделе Подключения Yandex Cloud. Вам нужно будет только создать подключение к нужной БД в кластере.

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

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

Убедитесь, что в настройках кластера включена опция Доступ из WebSQL.
Откройте Подключения Yandex WebSQL.
В разделе Подключения нажмите .
Укажите Имя подключения.
В поле Тип базы данных выберите нужную БД: PostgreSQL, ClickHouse®, MySQL®, Redis.
В поле Кластер выберите кластер управляемых БД, к которому вы хотите подключиться.
Укажите Имя пользователя, от лица которого будете подключаться к БД в кластере.
Введите Пароль пользователя.
Перечислите Базы данных, к которым вы хотите подключиться. Вы можете подключиться только к существующим в этом кластере БД. У пользователя, которого вы указали, должен быть настроен доступ к ним.
Нажмите Создать.

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

В разделе Подключения выберите базу данных, таблицу или представление.
На панели данных появится форма с запросом по умолчанию:
```
SELECT * FROM <имя_таблицы> LIMIT 10;
```
Используйте этот запрос или измените его. Интерфейс подскажет вам возможные части запроса и подсветит ошибки.
Нажмите кнопку Выполнить.

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

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

Windows/Linux

macOS

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

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

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

Подготовка к подключению из 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.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.

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

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

clickhouse-clientclickhouse-client

cURLcURL

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

Windows (PowerShell)Windows (PowerShell)

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

DataGripDataGrip

DBeaverDBeaver

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

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

Сервис Yandex WebSQLСервис Yandex WebSQL

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

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

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

clickhouse-client

cURL

Linux (Bash)/macOS (Zsh)

Windows (PowerShell)

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

DataGrip

DBeaver

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

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

Сервис Yandex WebSQL

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