Интерфейс MySQL

ClickHouse поддерживает сетевой протокол MySQL (MySQL wire protocol). Это позволяет некоторым клиентам, у которых нет нативных коннекторов для ClickHouse, использовать вместо них протокол MySQL. Он был проверен со следующими BI‑инструментами:

• Looker Studio
• Tableau Online
• QuickSight

Если вы пробуете другие, ещё не протестированные клиенты или интеграции, имейте в виду, что возможны следующие ограничения:

• Реализация SSL может быть не полностью совместима; возможны проблемы с TLS SNI.
• Конкретный инструмент может требовать особенности диалекта (например, функции или настройки, специфичные для MySQL), которые ещё не реализованы.

Если доступен нативный драйвер (например, DBeaver), всегда предпочтительнее использовать его вместо интерфейса MySQL. Кроме того, хотя большинство MySQL‑клиентов должно работать корректно, интерфейс MySQL не гарантирует полной взаимозаменяемости с кодовой базой, использующей существующие MySQL‑запросы.

Если ваш сценарий использования зависит от конкретного инструмента, у которого нет нативного драйвера для ClickHouse, и вы хотите использовать его через интерфейс MySQL и обнаружили определённые несовместимости — пожалуйста, создайте issue в репозитории ClickHouse.

Примечание

Для более полной поддержки SQL‑диалекта перечисленных выше BI‑инструментов интерфейс MySQL в ClickHouse неявно выполняет SELECT‑запросы с настройкой prefer_column_name_to_alias = 1. Эту опцию нельзя отключить, и в редких пограничных случаях это может приводить к отличающемуся поведению между запросами, отправленными через обычный интерфейс ClickHouse и через MySQL‑интерфейс.

Включение интерфейса MySQL в ClickHouse Cloud

1. После создания сервиса ClickHouse Cloud нажмите кнопку Connect.

2. В выпадающем списке Connect with выберите MySQL.

3. Переключите тумблер, чтобы включить интерфейс MySQL для этого сервиса. Для него будет открыт порт 3306, и отобразится экран подключения MySQL с вашим уникальным именем пользователя MySQL. Пароль будет таким же, как пароль пользователя по умолчанию для сервиса.

Скопируйте отображаемую строку подключения MySQL.

Создание нескольких пользователей MySQL в ClickHouse Cloud

По умолчанию существует встроенный пользователь mysql4<subdomain>, который использует тот же пароль, что и пользователь default. Часть <subdomain> — это первый сегмент имени хоста ClickHouse Cloud. Такой формат необходим для работы с инструментами, которые реализуют защищённое соединение, но не передают информацию SNI в своём TLS-рукопожатии, из‑за чего невозможно выполнить внутреннюю маршрутизацию без дополнительной подсказки в имени пользователя (консольный клиент MySQL — один из таких инструментов).

По этой причине мы настоятельно рекомендуем следовать формату mysql4<subdomain>_<username> при создании нового пользователя, предназначенного для работы с интерфейсом MySQL, где <subdomain> — это подсказка для идентификации вашего Cloud-сервиса, а <username> — произвольный суффикс по вашему выбору.

Совет

Для имени хоста ClickHouse Cloud вида foobar.us-east1.aws.clickhouse.cloud часть <subdomain> равна foobar, и настраиваемое имя пользователя MySQL может выглядеть как mysql4foobar_team1.

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

1. Необязательно — создайте профиль настроек, который будет применяться к вашему пользовательскому пользователю. Например, my_custom_profile с дополнительной настройкой, которая будет применяться по умолчанию при подключении с использованием пользователя, которого мы создадим позже:

   CREATE SETTINGS PROFILE my_custom_profile SETTINGS prefer_column_name_to_alias=1;
   

   prefer_column_name_to_alias используется только в качестве примера, вы можете использовать там и другие настройки.

2. Создайте пользователя, используя следующий формат: mysql4<subdomain>_<username> (см. выше). Пароль должен быть в формате double SHA1. Например:

   CREATE USER mysql4foobar_team1 IDENTIFIED WITH double_sha1_password BY 'YourPassword42$';
   

   или, если вы хотите использовать пользовательский профиль для этого пользователя:

   CREATE USER mysql4foobar_team1 IDENTIFIED WITH double_sha1_password BY 'YourPassword42$' SETTINGS PROFILE 'my_custom_profile';
   

   где my_custom_profile — имя профиля, который вы создали ранее.

3. Предоставьте новому пользователю необходимые права доступа для работы с нужными таблицами или базами данных. Например, если вы хотите предоставить доступ только к system.query_log:

   GRANT SELECT ON system.query_log TO mysql4foobar_team1;
   

4. Используйте созданного пользователя для подключения к вашему сервису ClickHouse Cloud через интерфейс MySQL.

Устранение неполадок при работе с несколькими пользователями MySQL в ClickHouse Cloud

Если вы создали нового пользователя MySQL и при подключении через CLI‑клиент MySQL видите следующую ошибку:

ERROR 2013 (HY000): Lost connection to MySQL server at 'reading authorization packet', system error: 54

В этом случае убедитесь, что имя пользователя соответствует формату mysql4<subdomain>_<username>, как описано (выше).

Включение интерфейса MySQL для самоуправляемого ClickHouse

Добавьте параметр mysql_port в конфигурационный файл сервера. Например, вы можете указать порт в новом XML-файле в каталоге config.d/ configuration files:

<clickhouse>
    <mysql_port>9004</mysql_port>
</clickhouse>

Запустите сервер ClickHouse и найдите в журнале сообщение, похожее на следующее, в котором присутствует строка Listening for MySQL compatibility protocol:

{} <Information> Application: Listening for MySQL compatibility protocol: 127.0.0.1:9004

Подключение MySQL к ClickHouse

Следующая команда демонстрирует, как подключить клиент MySQL mysql к ClickHouse:

mysql --protocol tcp -h [hostname] -u [username] -P [port_number] [database_name]

Например:

$ mysql --protocol tcp -h 127.0.0.1 -u default -P 9004 default

Вывод при успешном подключении:

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 4
Server version: 20.2.1.1-ClickHouse

Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

Для совместимости со всеми клиентами MySQL рекомендуется указывать пароль пользователя в конфигурационном файле в виде двойного SHA1. Если пароль пользователя задан с использованием SHA256, некоторые клиенты не смогут пройти аутентификацию (mysqljs и старые версии консольных утилит MySQL и MariaDB).

Ограничения:

• подготовленные запросы не поддерживаются

• некоторые типы данных передаются в виде строк

Чтобы отменить длительный запрос, используйте оператор KILL QUERY connection_id (при выполнении он заменяется на KILL QUERY WHERE query_id = connection_id). Например:

$ mysql --protocol tcp -h mysql_server -P 9004 default -u default --password=123 -e "KILL QUERY 123456;"