diff --git a/docs/_snippets/_clickhouse_mysql_cloud_setup.mdx b/docs/_snippets/_clickhouse_mysql_cloud_setup.mdx index 860da6c9914..55e0a84ee48 100644 --- a/docs/_snippets/_clickhouse_mysql_cloud_setup.mdx +++ b/docs/_snippets/_clickhouse_mysql_cloud_setup.mdx @@ -4,75 +4,107 @@ import mysql_3 from '@site/static/images/_snippets/mysql3.png'; import mysql_4 from '@site/static/images/_snippets/mysql4.png'; import mysql_5 from '@site/static/images/_snippets/mysql5.png'; import Image from '@theme/IdealImage'; +import {VerticalStepper} from "@clickhouse/click-ui/bundled"; -
-1. After creating your ClickHouse Cloud Service, on the `Connect your app` screen, select MySQL from the drop down. -
+ -ClickHouse Cloud credentials screen showing MySQL interface selection dropdown +#### Select `Connect your app` {#select-connect-your-app} -2. Toggle the switch to enable the MySQL interface for this specific service. This will expose port `3306` for this service and prompt you with your MySQL connection screen that include your unique MySQL username. +After creating your ClickHouse Cloud Service, on the `Connect your app` screen, select MySQL from the drop down. -ClickHouse Cloud MySQL interface enabling toggle and connection details -
+ClickHouse Cloud credentials screen showing MySQL interface selection dropdown + +#### Enable the MySQL interface {#enable-mysql-interface} + +Toggle the switch to enable the MySQL interface for this specific service. +This will expose port `3306` for this service and prompt you with a MySQL connection screen that includes your unique MySQL username. + +ClickHouse Cloud MySQL interface enabling toggle and connection details Alternatively, in order to enable the MySQL interface for an existing service: -3. Ensure your service is in `Running` state then click on the service you want to enable the MySQL interface for. Select "Connect" from the left menu: +#### Select `Connect` {#select-connect} + +Ensure your service is in `Running` state then click on the service you want to enable the MySQL interface for. +Select "Connect" from the left menu: + +ClickHouse Cloud service connection screen with Connect option highlighted -
-ClickHouse Cloud service connection screen with Connect option highlighted -
+#### Choose `MySQL` {#choose-mysql} -4. Select MySQL from the `Connect With` drop down. +Select `MySQL` from the `Connect With` drop down. -
ClickHouse Cloud connection screen showing MySQL option selection -
-5. Toggle the switch to enable the MySQL interface for this specific service. This will expose port `3306` for this service and prompt you with your MySQL connection screen that include your unique MySQL username. +#### Enable the MySQL interface {#enable-mysql-interface} + +Toggle the switch to enable the MySQL interface for this specific service. +This will expose port `3306` for this service and prompt you with your MySQL connection screen that include your unique MySQL username. + +
ClickHouse Cloud connection screen with MySQL interface enabled showing connection details -## Creating multiple MySQL users in ClickHouse Cloud {#creating-multiple-mysql-users-in-clickhouse-cloud} +## Creating a readonly MySQL user in ClickHouse Cloud {#creating-multiple-mysql-users-in-clickhouse-cloud} -By default, there is a built-in `mysql4` user, which uses the same password as the `default` one. The `` part is the first segment of your ClickHouse Cloud hostname. This format is necessary to work with the tools that implement secure connection, but don't provide [SNI information in their TLS handshake](https://www.cloudflare.com/learning/ssl/what-is-sni), which makes it impossible to do the internal routing without an extra hint in the username (MySQL console client is one of such tools). +ClickHouse Cloud automatically creates a `mysql4` user that shares the same password as the default user. +The `` portion corresponds to the first part of your ClickHouse Cloud hostname. -Because of this, we _highly recommend_ following the `mysql4_` format when creating a new user intended to be used with the MySQL interface, where `` is a hint to identify your Cloud service, and `` is an arbitrary suffix of your choice. +This username format is required for compatibility with tools that establish secure connections but don't include [SNI (Server Name Indication)](https://www.cloudflare.com/learning/ssl/what-is-sni) data in their TLS handshake. +Without SNI information, the system cannot perform proper internal routing, so the subdomain hint embedded in the username provides the necessary routing information. +The MySQL console client is an example of a tool that requires this. :::tip -For ClickHouse Cloud hostname like `foobar.us-east1.aws.clickhouse.cloud`, the `` part equals to `foobar`, and a custom MySQL username could look like `mysql4foobar_team1`. +A recommended best practice is to create a new readonly MySQL user. ::: -You can create extra users to use with the MySQL interface if, for example, you need to apply extra settings. +:::note +For a ClickHouse Cloud hostname like `foobar.us-east1.aws.clickhouse.cloud`, the `` part equals to `foobar`, and a custom MySQL username could look like `mysql4foobar_team1`. +::: -1. Optional - create a [settings profile](/sql-reference/statements/create/settings-profile) to apply for your custom user. For example, `my_custom_profile` with an extra setting which will be applied by default when we connect with the user we create later: + - ```sql - CREATE SETTINGS PROFILE my_custom_profile SETTINGS prefer_column_name_to_alias=1; - ``` +#### Create a readonly settings profile {#create-a-custom-settings-user} - `prefer_column_name_to_alias` is used just as an example, you can use other settings there. -2. [Create a user](/sql-reference/statements/create/user) using the following format: `mysql4_` ([see above](#creating-multiple-mysql-users-in-clickhouse-cloud)). The password must be in double SHA1 format. For example: +Create a [settings profile](/sql-reference/statements/create/settings-profile) to apply to your readonly user, +setting the `readonly` setting to `1`: - ```sql - CREATE USER mysql4foobar_team1 IDENTIFIED WITH double_sha1_password BY 'YourPassword42$'; - ``` +```sql +CREATE SETTINGS PROFILE readonly_profile SETTINGS readonly = 1 +``` - or if you want to use a custom profile for this user: +#### Create a new readonly MySQL user {#create-a-readonly-mysql-user} - ```sql - CREATE USER mysql4foobar_team1 IDENTIFIED WITH double_sha1_password BY 'YourPassword42$' SETTINGS PROFILE 'my_custom_profile'; - ``` +[Create a user](/sql-reference/statements/create/user) with a name following this format: - where `my_custom_profile` is the name of the profile you created earlier. -3. [Grant](/sql-reference/statements/grant) the new user the necessary permissions to interact with the desired tables or databases. For example, if you want to grant access to `system.query_log` only: +```sql +mysql4_ +``` + +Apply the `readonly_profile` to the new user and make sure that the password is in double SHA1 format. For example: + +```sql +CREATE USER mysql4foobar_readonly +IDENTIFIED WITH double_sha1_password BY 'YourPassword42$' +SETTINGS PROFILE 'readonly_profile'; +``` + +#### Grant the new user permissions to access the desired tables {#grant-the-new-user-the-necessary-permissions} + +[Grant](/sql-reference/statements/grant) the new user the necessary permissions to interact with the desired tables or databases. +For example, if you want to grant access to `system.query_log` only: + +```sql +GRANT SELECT ON system.query_log TO mysql4foobar_readonly; +``` + +:::note +For the readonly user, make sure to only grant `SELECT` permissions to the tables you want to access. +::: - ```sql - GRANT SELECT ON system.query_log TO mysql4foobar_team1; - ``` +The newly created user can be used to connect to your ClickHouse Cloud service with the MySQL interface. -4. Use the created user to connect to your ClickHouse Cloud service with the MySQL interface. + ### Troubleshooting multiple MySQL users in ClickHouse Cloud {#troubleshooting-multiple-mysql-users-in-clickhouse-cloud}