Merge pull request #8726 from yurriy/mysql-protocol-docs

MySQL compatibility server docs

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
+<mysql_port>9004</mysql_port>
+```
+
+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

docs/en/operations/server_settings/settings.md

@@ -709,6 +709,20 @@ Positive integer.
 <tcp_port_secure>9440</tcp_port_secure>
 ```
 
+## mysql_port {#server_settings-mysql_port}
+
+Port for communicating with clients over MySQL protocol.
+
+**Possible values**
+
+Positive integer.
+
+Example
+
+```xml
+<mysql_port>9004</mysql_port>
+```
+
 ## tmp_path
 
 Path to temporary data for processing large queries.

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, `<password>qwerty</password>`. The password can be left blank.
 
+<a id="password_sha256_hex"></a>
+
 - To assign a password using its SHA256 hash, place it in a `password_sha256_hex` element.
 
     For example, `<password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>`.
@@ -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.
 
+<a id="password_double_sha1_hex"></a>
+
+- For compatibility with MySQL clients, password can be specified in double SHA1 hash. Place it in `password_double_sha1_hex` element.
+
+    For example, `<password_double_sha1_hex>08b4a0f1de6ad37da17359e592c8d74788a83eb0</password_double_sha1_hex>`.
+
+    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
 

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
+<mysql_port>9004</mysql_port>
+```
+
+Пример подключения с помощью стандартного клиента 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).
+
+Ограничения:
+- не поддерживаются подготовленные запросы
+- некоторые типы данных отправляются как строки

docs/ru/operations/server_settings/settings.md

@@ -661,6 +661,16 @@ TCP порт для защищённого обмена данными с кли
 <tcp_port_secure>9440</tcp_port_secure>
 ```
 
+## mysql_port {#server_settings-mysql_port}
+
+Порт для взаимодействия с клиентами по протоколу MySQL.
+
+Пример
+
+```xml
+<mysql_port>9004</mysql_port>
+```
+
 ## tmp_path
 
 Путь ко временным данным для обработки больших запросов.

docs/ru/operations/settings/settings_users.md

@@ -39,6 +39,8 @@
 
     Например, `<password>qwerty</password>`. Пароль можно оставить пустым.
 
+<a id="password_sha256_hex"></a>
+
 - Чтобы назначить пароль в виде SHA256, поместите хэш в элемент `password_sha256_hex`.
 
     Например, `<password_sha256_hex>65e84be33532fb784c48129675f9eff3a682b27168c0ea744b2cf58ee02337c5</password_sha256_hex>`.
@@ -51,6 +53,20 @@
 
     Первая строка результата — пароль. Вторая строка — соответствующий ему хэш SHA256.
 
+<a id="password_double_sha1_hex"></a>
+
+- Для совместимости с клиентами MySQL, пароль можно задать с помощью двойного хэша SHA1, поместив его в элемент `password_double_sha1_hex`.
+
+    Например, `<password_double_sha1_hex>08b4a0f1de6ad37da17359e592c8d74788a83eb0</password_double_sha1_hex>`.
+
+    Пример создания пароля в командной строке:
+
+    ```
+    PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | openssl dgst -sha1 -binary | openssl dgst -sha1
+    ```
+
+    Первая строка результата — пароль. Вторая строка — соответствующий ему двойной хэш SHA1.
+
 ### user_name/networks
 
 Список сетей, из которых пользователь может подключиться к серверу ClickHouse.

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'

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'