Merge branch 'main' of https://github.com/ClickHouse/clickhouse-docs into add-lakekeeper-catalog

Author: Blargian

.github/workflows/check-build.yml

@@ -16,15 +16,15 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        check_type: [spellcheck, kbcheck, md-lint]
+        check_type: [spellcheck, kbcheck, md-lint, glossary-check]
     steps:
       # Add setup steps per check here
       - uses: actions/checkout@v4
       - name: Install Aspell
         if: matrix.check_type == 'spellcheck'
         run: sudo apt-get update && sudo apt-get install -y aspell aspell-en
       - name: Set up Python
-        if: matrix.check_type == 'kbcheck'
+        if: matrix.check_type == 'kbcheck' || matrix.check_type == 'glossary-check'
         run: |
           curl -Ls https://astral.sh/uv/install.sh | sh
           uv clean
@@ -39,31 +39,25 @@ jobs:
         run: yarn add -D markdownlint-cli2
 
       # Run the checks here
-      - name: Run checks
-        id: check_step
-        run: |
-          if [[ "${{ matrix.check_type }}" == "spellcheck" ]]; then
-            yarn check-spelling
-          exit_code=$?
-          elif [[ "${{ matrix.check_type }}" == "kbcheck" ]]; then
-            yarn check-kb
-          exit_code=$?
-          elif [[ "${{ matrix.check_type }}" == "md-lint" ]]; then
-            yarn check-markdown
-          exit_code=$?
-          fi
-          
-          if [[ $exit_code -ne 0 ]]; then
-            echo "::error::${{ matrix.check_type }} check failed. See logs for details."
-            exit 1
-          fi
+      - name: Run spellcheck
+        if: matrix.check_type == 'spellcheck'
+        run: yarn check-spelling
 
-      - name: Set check status
-        if: steps.check_step.outcome != 'success'
-        uses: actions/github-script@v6
-        with:
-          script: |
-            core.setFailed('${{ matrix.check_type }} check failed.');
+      - name: Run KB check  
+        if: matrix.check_type == 'kbcheck'
+        run: yarn check-kb
+
+      - name: Run markdown lint
+        if: matrix.check_type == 'md-lint' 
+        run: yarn check-markdown
+
+      - name: Run glossary check
+        if: matrix.check_type == 'glossary-check'
+        run: |
+          echo "Extracting glossary from markdown..."
+          python3 scripts/glossary/extract-glossary-terms.py
+          echo "Checking glossary coverage..."
+          python3 scripts/glossary/wrap-glossary-terms.py --check || echo "::warning::Glossary check found unwrapped terms (non-blocking)"
           
   check_overall_status:
     needs: stylecheck
@@ -74,5 +68,4 @@ jobs:
         if: needs.stylecheck.result != 'success'
         run: |
           echo "::error::One or more checks of the style check failed."
-          exit 1
-          
+          exit 1

.github/workflows/trademark-cla-approval.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Generate Token
         id: generate-token
         continue-on-error: true
-        uses: actions/create-github-app-token@v1
+        uses: actions/create-github-app-token@v2
         with:
           app-id: "${{ secrets.WORKFLOW_AUTH_PUBLIC_APP_ID }}"
           private-key: "${{ secrets.WORKFLOW_AUTH_PUBLIC_PRIVATE_KEY }}"

.github/workflows/trademark-cla-notice.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Generate Token
         id: generate-token
         continue-on-error: true
-        uses: actions/create-github-app-token@v1
+        uses: actions/create-github-app-token@v2
         with:
           app-id: "${{ secrets.WORKFLOW_AUTH_PUBLIC_APP_ID }}"
           private-key: "${{ secrets.WORKFLOW_AUTH_PUBLIC_PRIVATE_KEY }}"

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";
 
-<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
+```
 
-    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}