Skip to content

MySQL: update MySQL connection instructions on how to make a readonly user #4267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 14, 2025
Merged

MySQL: update MySQL connection instructions on how to make a readonly user #4267

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 71 additions & 39 deletions docs/_snippets/_clickhouse_mysql_cloud_setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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";

<br/>
1. After creating your ClickHouse Cloud Service, on the `Connect your app` screen, select MySQL from the drop down.
<br/>
<VerticalStepper headerLevel="h4">

<Image size="md" img={mysql_1} alt="ClickHouse Cloud credentials screen showing MySQL interface selection dropdown" border />
#### 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.

<Image size="md" img={mysql_2} alt="ClickHouse Cloud MySQL interface enabling toggle and connection details" border />
<br/>
<Image size="lg" img={mysql_1} alt="ClickHouse Cloud credentials screen showing MySQL interface selection dropdown" border />

#### 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.

<Image size="lg" img={mysql_2} alt="ClickHouse Cloud MySQL interface enabling toggle and connection details" border />

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:

<Image size="lg" img={mysql_3} alt="ClickHouse Cloud service connection screen with Connect option highlighted" border />

<br/>
<Image size="md" img={mysql_3} alt="ClickHouse Cloud service connection screen with Connect option highlighted" border />
<br/>
#### Choose `MySQL` {#choose-mysql}

4. Select MySQL from the `Connect With` drop down.
Select `MySQL` from the `Connect With` drop down.

<br/>
<Image size="md" img={mysql_4} alt="ClickHouse Cloud connection screen showing MySQL option selection" border />
<br/>

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.

</VerticalStepper>

<Image size="md" img={mysql_5} alt="ClickHouse Cloud connection screen with MySQL interface enabled showing connection details" border />

## 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<subdomain>` user, which uses the same password as the `default` one. The `<subdomain>` 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<subdomain>` user that shares the same password as the default user.
The `<subdomain>` portion corresponds to the first part of your ClickHouse Cloud hostname.

Because of this, we _highly recommend_ following the `mysql4<subdomain>_<username>` format when creating a new user intended to be used with the MySQL interface, where `<subdomain>` is a hint to identify your Cloud service, and `<username>` 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 `<subdomain>` 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 `<subdomain>` 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:
<VerticalStepper headerLevel="h4">

```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<subdomain>_<username>` ([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
Copy link
Member

@mshustov mshustov Aug 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure whether we need readonly = 1 (strict mode) or readonly = 2 (allow changing some settings https://clickhouse.com/docs/operations/settings/permissions-for-queries#readonly)

```

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<subdomain>_<username>
```

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.
</VerticalStepper>

### Troubleshooting multiple MySQL users in ClickHouse Cloud {#troubleshooting-multiple-mysql-users-in-clickhouse-cloud}

Expand Down