From 78959668048db18a5ae0e2d70d986f466dd9786c Mon Sep 17 00:00:00 2001 From: Yuriy Date: Sun, 19 Jan 2020 08:57:21 +0300 Subject: [PATCH 1/2] initial MySQL compatibility server docs --- docs/en/interfaces/mysql.md | 35 +++++++++++++++++++ .../en/operations/server_settings/settings.md | 14 ++++++++ docs/en/operations/settings/settings_users.md | 17 ++++++++- docs/ru/interfaces/mysql.md | 35 +++++++++++++++++++ .../ru/operations/server_settings/settings.md | 10 ++++++ docs/ru/operations/settings/settings_users.md | 16 +++++++++ docs/toc_en.yml | 1 + docs/toc_ru.yml | 1 + 8 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 docs/en/interfaces/mysql.md create mode 100644 docs/ru/interfaces/mysql.md diff --git a/docs/en/interfaces/mysql.md b/docs/en/interfaces/mysql.md new file mode 100644 index 00000000000..1c56eaffb82 --- /dev/null +++ b/docs/en/interfaces/mysql.md @@ -0,0 +1,35 @@ +# MySQL interface {#mysql_interface} + +ClickHouse supports MySQL wire protocol. It can be enabled by [mysql_port](../operations/server_settings/settings.md#server_settings-mysql_port) setting in configuration file: +```xml +9004 +``` + +Example of connecting using command-line tool mysql: +```bash +$ mysql --protocol tcp -u default -P 9004 +``` + +Output if connection succeeded: +```text +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> +``` + +For compatibility with all MySQL clients, it is recommended to specify user password with [double SHA1](../operations/settings/settings_users.md#password_double_sha1_hex) in configuration file. +If user password is specified using [SHA256](../operations/settings/settings_users.md#password_sha256_hex), some clients won't be able to authenticate (mysqljs and old versions of command-line tool mysql). + +Restrictions: +- prepared queries are not supported +- some data types are sent as strings diff --git a/docs/en/operations/server_settings/settings.md b/docs/en/operations/server_settings/settings.md index 89bb7ef33ae..c13d53eabc7 100644 --- a/docs/en/operations/server_settings/settings.md +++ b/docs/en/operations/server_settings/settings.md @@ -709,6 +709,20 @@ Positive integer. 9440 ``` +## mysql_port {#server_settings-mysql_port} + +Port for communicating with clients over MySQL protocol. + +**Possible values** + +Positive integer. + +Example + +```xml +9004 +``` + ## tmp_path Path to temporary data for processing large queries. diff --git a/docs/en/operations/settings/settings_users.md b/docs/en/operations/settings/settings_users.md index 8937c59b667..5289bb19645 100644 --- a/docs/en/operations/settings/settings_users.md +++ b/docs/en/operations/settings/settings_users.md @@ -33,12 +33,14 @@ Structure of the `users` section: ### user_name/password -Password could be specified in plaintext or in SHA256 (hex format). +Password can be specified in plaintext or in SHA256 (hex format). - To assign a password in plaintext (**not recommended**), place it in a `password` element. For example, `qwerty`. The password can be left blank. + + - To assign a password using its SHA256 hash, place it in a `password_sha256_hex` element. For example, `65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5`. @@ -51,6 +53,19 @@ Password could be specified in plaintext or in SHA256 (hex format). The first line of the result is the password. The second line is the corresponding SHA256 hash. + + +- For compatibility with MySQL clients, password can be specified in double SHA1 hash. Place it in `password_double_sha1_hex` element. + + For example, `08b4a0f1de6ad37da17359e592c8d74788a83eb0`. + + Example of how to generate a password from shell: + + ``` + PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | openssl dgst -sha1 -binary | openssl dgst -sha1 + ``` + + The first line of the result is the password. The second line is the corresponding double SHA1 hash. ### user_name/networks diff --git a/docs/ru/interfaces/mysql.md b/docs/ru/interfaces/mysql.md new file mode 100644 index 00000000000..cd1c525d327 --- /dev/null +++ b/docs/ru/interfaces/mysql.md @@ -0,0 +1,35 @@ +# MySQL-интерфейс {#mysql_interface} + +ClickHouse поддерживает взаимодействие по протоколу MySQL. Для включения этой опции необходимо добавить в конфигурационный файл настройку [mysql_port](../operations/server_settings/settings.md#server_settings-mysql_port): +```xml +9004 +``` + +Пример подключения с помощью стандартного клиента mysql: +```bash +$ mysql --protocol tcp -u default -P 9004 +``` + +Вывод в случае успешного подключения: +```text +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> +``` + +Для совместимости со всеми клиентами рекомендуется задавать пароль пользователя в конфигурационном файле с помощью двойного хэша [SHA1](../operations/settings/settings_users.md#password_double_sha1_hex). +При указании пароля с помощью [SHA256](../operations/settings/settings_users.md#password_sha256_hex) некоторые клиенты не смогут пройти аутентификацию (mysqljs и старые версии стандартного клиента mysql). + +Ограничения: +- не поддерживаются подготовленные запросы +- некоторые типы данных отправляются как строки diff --git a/docs/ru/operations/server_settings/settings.md b/docs/ru/operations/server_settings/settings.md index 9072b2a6376..de0cf7d2a41 100644 --- a/docs/ru/operations/server_settings/settings.md +++ b/docs/ru/operations/server_settings/settings.md @@ -661,6 +661,16 @@ TCP порт для защищённого обмена данными с кли 9440 ``` +## mysql_port {#server_settings-mysql_port} + +Порт для взаимодействия с клиентами по протоколу MySQL. + +Пример + +```xml +9004 +``` + ## tmp_path Путь ко временным данным для обработки больших запросов. diff --git a/docs/ru/operations/settings/settings_users.md b/docs/ru/operations/settings/settings_users.md index dfa3e40c660..11f7d925671 100644 --- a/docs/ru/operations/settings/settings_users.md +++ b/docs/ru/operations/settings/settings_users.md @@ -39,6 +39,8 @@ Например, `qwerty`. Пароль можно оставить пустым. + + - Чтобы назначить пароль в виде SHA256, поместите хэш в элемент `password_sha256_hex`. Например, `65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5`. @@ -51,6 +53,20 @@ Первая строка результата — пароль. Вторая строка — соответствующий ему хэш SHA256. + + +- Для совместимости с клиентами MySQL, пароль можно задать с помощью двойного хэша SHA1, поместив его в элемент `password_double_sha1_hex`. + + Например, `08b4a0f1de6ad37da17359e592c8d74788a83eb0`. + + Пример создания пароля в командной строке: + + ``` + PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | openssl dgst -sha1 -binary | openssl dgst -sha1 + ``` + + Первая строка результата — пароль. Вторая строка — соответствующий ему двойной хэш SHA1. + ### user_name/networks Список сетей, из которых пользователь может подключиться к серверу ClickHouse. diff --git a/docs/toc_en.yml b/docs/toc_en.yml index 604aca5d18e..f5bbea39945 100644 --- a/docs/toc_en.yml +++ b/docs/toc_en.yml @@ -25,6 +25,7 @@ nav: - 'Command-Line Client': 'interfaces/cli.md' - 'Native Interface (TCP)': 'interfaces/tcp.md' - 'HTTP Interface': 'interfaces/http.md' + - 'MySQL Interface': 'interfaces/mysql.md' - 'Input and Output Formats': 'interfaces/formats.md' - 'JDBC Driver': 'interfaces/jdbc.md' - 'ODBC Driver': 'interfaces/odbc.md' diff --git a/docs/toc_ru.yml b/docs/toc_ru.yml index dc6a0d9227c..cd422773282 100644 --- a/docs/toc_ru.yml +++ b/docs/toc_ru.yml @@ -26,6 +26,7 @@ nav: - 'Клиент командной строки': 'interfaces/cli.md' - 'Нативный интерфейс (TCP)': 'interfaces/tcp.md' - 'HTTP-интерфейс': 'interfaces/http.md' + - 'MySQL-интерфейс': 'interfaces/mysql.md' - 'Форматы входных и выходных данных': 'interfaces/formats.md' - 'JDBC-драйвер': 'interfaces/jdbc.md' - 'ODBC-драйвер': 'interfaces/odbc.md' From 5f806e7a394135b1ff9da1e56bd4cb4ba1f7d1db Mon Sep 17 00:00:00 2001 From: Yuriy Date: Sun, 19 Jan 2020 09:10:15 +0300 Subject: [PATCH 2/2] better docs --- docs/ru/interfaces/mysql.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ru/interfaces/mysql.md b/docs/ru/interfaces/mysql.md index cd1c525d327..8f01d5afb44 100644 --- a/docs/ru/interfaces/mysql.md +++ b/docs/ru/interfaces/mysql.md @@ -1,6 +1,6 @@ # MySQL-интерфейс {#mysql_interface} -ClickHouse поддерживает взаимодействие по протоколу MySQL. Для включения этой опции необходимо добавить в конфигурационный файл настройку [mysql_port](../operations/server_settings/settings.md#server_settings-mysql_port): +ClickHouse поддерживает взаимодействие по протоколу MySQL. Данная функция включается настройкой [mysql_port](../operations/server_settings/settings.md#server_settings-mysql_port) в конфигурационном файле: ```xml 9004 ``` @@ -28,7 +28,7 @@ mysql> ``` Для совместимости со всеми клиентами рекомендуется задавать пароль пользователя в конфигурационном файле с помощью двойного хэша [SHA1](../operations/settings/settings_users.md#password_double_sha1_hex). -При указании пароля с помощью [SHA256](../operations/settings/settings_users.md#password_sha256_hex) некоторые клиенты не смогут пройти аутентификацию (mysqljs и старые версии стандартного клиента mysql). +В случае указания пароля с помощью [SHA256](../operations/settings/settings_users.md#password_sha256_hex) некоторые клиенты не смогут пройти аутентификацию (mysqljs и старые версии стандартного клиента mysql). Ограничения: - не поддерживаются подготовленные запросы