[Yandex Cloud documentation](../../../index.md) > [Yandex Managed Service for ClickHouse®](../../index.md) > [Step-by-step guides](../index.md) > [Connection](index.md) > Connecting from applications

# Connecting to a ClickHouse® cluster from applications

This section provides settings for connecting to Managed Service for ClickHouse® cluster hosts using the [command line tools](#command-line-tools), [graphical IDEs](#ide), [browser](#browser), and [Docker container](#docker). See [Code examples](code-examples.md) to learn how to connect from application code.


You can only connect to public ClickHouse® cluster hosts using [SSL certificates](index.md#get-ssl-cert). The examples below assume that the `RootCA.crt` and `IntermediateCA.crt` certificates are:

* Located in the `/usr/local/share/ca-certificates/Yandex/` directory (for Ubuntu).
* Imported to the trusted root certificate store (for Windows).

Connecting without SSL certificates is only supported for non-public hosts. If this is the case, internal virtual network traffic will not be encrypted for database connections.

Before connecting, [configure security groups](index.md#configure-security-groups) for the cluster, if required.


The examples for Linux were tested in the following environment:

* Yandex Cloud VM running Ubuntu 20.04 LTS.
* Bash: `5.0.16`.

The examples for Windows were tested in the following environment:

* Local machine with Windows 10 Pro build `19042.1052`.
* PowerShell: `5.1.19041`.

## Command line tools {#command-line-tools}

To see code examples with the host FQDN filled in, open the cluster page in the [management console](https://console.yandex.cloud) and click **Connect**.


### clickhouse-client {#clickhouse-client}

**Before connecting**:

1. Add the ClickHouse® [DEB repository](https://clickhouse.com/docs/enen/install#install-from-deb-packages):

    ```bash
    sudo apt update && sudo apt install --yes apt-transport-https ca-certificates dirmngr && \
    sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754 && \
    echo "deb https://packages.clickhouse.com/deb stable main" | sudo tee \
    /etc/apt/sources.list.d/clickhouse.list
    ```

1. Install the dependencies:

    ```bash
    sudo apt update && sudo apt install --yes clickhouse-client
    ```

1. Download the `clickhouse-client` configuration file:

   ```bash
   mkdir -p ~/.clickhouse-client && \
   wget "https://storage.yandexcloud.net/doc-files/clickhouse-client.conf.example" \
     --output-document ~/.clickhouse-client/config.xml
   ```

{% list tabs group=connection %}


- Connecting without SSL {#without-ssl}

    ```bash
    clickhouse-client --host <FQDN_of_any_ClickHouse®_host> \
                      --user <username> \
                      --database <DB_name> \
                      --port 9000 \
                      --ask-password
    ```


- Connecting with SSL {#with-ssl}

  ```bash
  clickhouse-client --host <FQDN_of_any_ClickHouse®_host> \
                    --secure \
                    --user <username> \
                    --database <DB_name> \
                    --port 9440 \
                    --ask-password
  ```

{% endlist %}

To learn how to get a host FQDN, see [this guide](fqdn.md).

After runing this command, enter the user password to complete your connection.

Once connected to the DBMS, run the `SELECT version();` command.

### mysql-client {#mysql-client}

{% note warning %}

You should only use the MySQL® client connection interface if you cannot use standard ClickHouse® interfaces.

{% endnote %}

Before connecting, install the `mysql` utility:

```bash
sudo apt update && sudo apt install --yes mysql-client
```

{% list tabs group=connection %}


- Connecting without SSL {#without-ssl}

    ```bash
    mysql --host=<FQDN_of_any_ClickHouse®_host> \
          --port=3306 \
          --ssl-mode=DISABLED \
          --user <username> \
          --password \
          <DB_name>
    ```


- Connecting with SSL {#with-ssl}

    ```bash
    mysql --host=<FQDN_of_any_ClickHouse®_host> \
          --port=3306 \
          --ssl-ca=/usr/local/share/ca-certificates/Yandex/RootCA.crt \
          --ssl-mode=VERIFY_IDENTITY \
          --user=<username> \
          --password \
          <DB_name>
    ```

{% endlist %}

To learn how to get a host’s FQDN, see [this guide](fqdn.md).

After running this command, enter the user password to complete your connection.

Once connected to the DBMS, run the `SELECT version();` command.

### cURL {#curl}

#### Linux (Bash)/macOS (Zsh) {#curl-bash-zsh}

{% list tabs group=connection %}


- Connecting without SSL {#without-ssl}

    ```bash
    curl --header "X-ClickHouse-User: <DB_user_name>" \
         --header "X-ClickHouse-Key: <DB_user_password>" \
         'http://<FQDN_of_any_ClickHouse®_host>:8123/?database=<DB_name>&query=SELECT%20version()'
    ```


- Connecting with SSL {#with-ssl}

    ```bash
    curl --cacert /usr/local/share/ca-certificates/Yandex/RootCA.crt \
         --header "X-ClickHouse-User: <DB_user_name>" \
         --header "X-ClickHouse-Key: <DB_user_password>" \
         'https://<FQDN_of_any_ClickHouse®_host>:8443/?database=<DB_name>&query=SELECT%20version()'
    ```

{% endlist %}

To learn how to get a host’s FQDN, see [this guide](fqdn.md).

#### Windows (PowerShell) {#curl-powershell}

{% list tabs group=connection %}


- Connecting without SSL {#without-ssl}

    ```powershell
    curl.exe `
        --header "X-ClickHouse-User: <DB_user_name>" `
        --header "X-ClickHouse-Key: <DB_user_password>" `
        'http://<FQDN_of_any_ClickHouse®_host>:8123/?database=<DB_name>&query=SELECT+version()'
    ```


- Connecting with SSL {#with-ssl}

    ```powershell
    curl.exe `
        --header "X-ClickHouse-User: <DB_user_name>" `
        --header "X-ClickHouse-Key: <DB_user_password>" `
        'https://<FQDN_of_any_ClickHouse®_host>:8443/?database=<DB_name>&query=SELECT+version()'
    ```

{% endlist %}

To learn how to get a host’s FQDN, see [this guide](fqdn.md).

## Connecting from graphical IDEs {#ide}

**Connections were tested in the following environment:**

* Ubuntu 20.04, DBeaver: `22.2.4`
* MacOS Monterey 12.7:
   * JetBrains DataGrip: `2023.3.4`
   * DBeaver Community: `24.0.0`


From graphical IDEs, you can only connect to public cluster hosts using an SSL certificate.


To avoid connection errors, [save the certificate](https://storage.yandexcloud.net/cloud-certs/RootCA.pem) to a local folder that does not require administrator rights to access.

### DataGrip {#datagrip}

1. Create a data source:
    1. Select **File** → **New** → **Data Source** → **ClickHouse®**.
    1. On the **General** tab:
        1. Configure the connection as follows:
            * **Host**: [FQDN of any ClickHouse® host](fqdn.md) or a [special FQDN](fqdn.md#auto).
            * **Port**: `8443`.
            * **User**, **Password**: Database user name and password.
            * **Database**: Name of the database to connect to.
        1. Click **Download** to download the connection driver.
    1. On the **SSH/SSL** tab:
        1. Enable **Use SSL**.
        1. Specify the directory that contains the file with the downloaded [SSL certificate for the connection](index.md#get-ssl-cert).
1. Click **Test Connection**. If the connection is successful, you will see the connection status and information about the DBMS and driver.
1. Click **OK** to save the data source.

### DBeaver {#dbeaver}

1. Create a new DB connection:
    1. In the **Database** menu, select **New connection**.
    1. Select **ClickHouse®** from the DB list.
    1. Click **Next**.
    1. Specify the connection settings on the **Main** tab:
        * **Host**: [FQDN of any ClickHouse® host](fqdn.md) or a [special FQDN](fqdn.md#auto).
        * **Port**: `8443`.
        * **DB/Schema**: Name of the database to connect to.
        * Under **Authentication**, specify the database user name and password.
    1. On the **Driver properties** tab:
        1. Click **Download** in the new window that prompts you to download the driver files.
        1. Specify the [SSL connection](index.md#get-ssl-cert) settings in the driver property list:
            * `ssl:true`
            * `sslrootcert:<path_to_saved_SSL_certificate_file>`.
1. Click **Test connection ...**. If the connection is successful, you will see the connection status, DBMS information, and driver details.
1. Click **Done** to save the database connection settings.


## Connecting to a cluster from your browser {#browser}

To run SQL queries from your browser, use:


* [ClickHouse® built-in SQL editor](#inline-editor)


* [Yandex WebSQL](#websql)



### ClickHouse® built-in SQL editor {#inline-editor}

To connect to a cluster host from the built-in SQL editor, specify the following in the browser address bar:

```text
https://<FQDN_of_any_ClickHouse®_host>:8443/play
```

You can only connect to public cluster hosts. To learn how to get a host’s FQDN, see [this guide](fqdn.md).

To connect to a cluster with [automatic selection of an available host](fqdn.md#auto), use the following URL:

* `https://c-<cluster_ID>.rw.mdb.yandexcloud.net:8443/play`: To connect to an available cluster host.
* `https://<shard_name>.c-<cluster_ID>.rw.mdb.yandexcloud.net:8443/play`: To connect to an available [shard](../../concepts/sharding.md) host.

To run database queries, enter your username and password in the top-right corner of the page.


When you connect from the built-in editor, SQL queries run separately without creating a shared session with the ClickHouse® server. Therefore, queries running within the session, such as `USE` or `SET`, have no effect.



### Yandex WebSQL {#websql}

{% note info %}

This feature is at the [Preview](../../../overview/concepts/launch-stages.md) stage.

{% endnote %}

Use [Yandex WebSQL](../../../websql/index.md) to connect to a ClickHouse® cluster in Yandex Cloud.

Before creating a connection, make sure you have selected the right folder. If you have access to PostgreSQL, ClickHouse®, MySQL®, Greenplum®, Valkey™, or Yandex StoreDoc clusters previously created in that folder, they will automatically appear in the **Yandex Cloud connections** subsection. You will only need to create a connection to the appropriate database in the cluster.


{% note info %}

[Yandex Managed Service for Trino](../../../managed-trino/index.md) is at the [Preview](../../../overview/concepts/launch-stages.md) stage. Currently, you cannot create connections to Yandex Managed Service for Trino in the Yandex WebSQL interface. However, if the current folder has a Yandex Managed Service for Trino cluster and the user can access it, the connection will be displayed in WebSQL, available for use. 

{% endnote %}


WebSQL uses connections in Yandex MetaData Hub Connection Manager, so all connections configured in Connection Manager are automatically available in WebSQL provided that the user has the appropriate [roles](../../../metadata-hub/security/index.md#service-roles).

To create a connection to a Yandex Cloud managed database cluster:

1. Make sure **WebSQL access** is enabled in the cluster settings.
1. Open Yandex WebSQL [**Connections**](https://websql.yandex.cloud).
1. In ![image](../../../_assets/console-icons/folder-tree.svg) **Connections**, click ![image](../../../_assets/console-icons/square-plus.svg).
1. In the **Database type** field, select the database you need: PostgreSQL, ClickHouse®, MySQL®, Valkey™, Yandex StoreDoc, or Greenplum®.
1. In the **Cluster folder** field, select the folder hosting the required cluster.
1. In the **Cluster** field, select the managed database cluster you want to connect to. 
1. Specify the **Username** you will use to connect to cluster databases.
1. Enter the user **Password**.
1. List the **Databases** you want to connect to. You can only connect to the databases that exist in this cluster. The user you specified must have access to them.
1. Click **Create**.

To build a query:
1. Under [**Connections**](https://websql.yandex.cloud), select a database, table, or image.
1. In the data panel, you will see a form with the default query:

   ```sql
   SELECT * FROM <table_name> LIMIT 10;
   ```
1. Use this query or edit it. The interface will suggest relevant parts of the query and highlight errors.
1. Click **Run**.

In the results panel, you will see a table with the query results.

When editing or running a query, you can use the following keyboard shortcuts (click ![image](../../../_assets/websql/questionmark.svg) to see the full list):

{% list tabs group=operating_system %}

- Windows/Linux {#window-linux}

   * Show suggestions: **Ctrl** + **I** , **Ctrl** + **Space**.
   * Comment out a line: **Ctrl** + **/**.
   * Run a query: **Ctrl** + **Enter**.

- macOS {#macos}

   * Show suggestions: **⌘** + **I** , **⌃** + **Space**.
   * Comment out a line: **⌘** + **/**.
   * Run a query: **⌘** + **⏎**.

{% endlist %}

Click ![image](../../../_assets/websql/palette.svg) **Open Command Palette** to view a complete list of available commands and their corresponding keyboard shortcuts.


## Before you connect from a Docker container {#docker}

To connect to a Managed Service for ClickHouse® cluster from a Docker container, add the following lines to your Dockerfile:

{% list tabs group=connection %}


- Connecting without SSL {#without-ssl}

   ```bash
   # Add the DEB repository.
   RUN apt-get update && \
       apt-get install wget --yes apt-transport-https ca-certificates dirmngr && \
       apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754 && \
       echo "deb https://packages.clickhouse.com/deb stable main" | tee \
       /etc/apt/sources.list.d/clickhouse.list && \
       # Install the dependencies.
       apt-get update && \
       apt-get install wget clickhouse-client --yes && \
       # Download the clickhouse-client configuration file.
       mkdir --parents ~/.clickhouse-client && \
       wget "https://storage.yandexcloud.net/doc-files/clickhouse-client.conf.example" \
            --output-document ~/.clickhouse-client/config.xml
   ```


- Connecting with SSL {#with-ssl}

   ```bash
   # Add the DEB repository.
   RUN apt-get update && \
       apt-get install wget --yes apt-transport-https ca-certificates dirmngr && \
       apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754 && \
       echo "deb https://packages.clickhouse.com/deb stable main" | tee \
       /etc/apt/sources.list.d/clickhouse.list && \
       # Install the dependencies.
       apt-get update && \
       apt-get install wget clickhouse-client --yes && \
       # Download the clickhouse-client configuration file.
       mkdir --parents ~/.clickhouse-client && \
       wget "https://storage.yandexcloud.net/doc-files/clickhouse-client.conf.example" \
            --output-document ~/.clickhouse-client/config.xml && \
       # Get SSL certificates.
       mkdir --parents /usr/local/share/ca-certificates/Yandex/ && \
       wget "https://storage.yandexcloud.net/cloud-certs/RootCA.pem" \
            --output-document /usr/local/share/ca-certificates/Yandex/RootCA.crt && \
       wget "https://storage.yandexcloud.net/cloud-certs/IntermediateCA.pem" \
            --output-document /usr/local/share/ca-certificates/Yandex/IntermediateCA.crt && \
       chmod 655 \
            /usr/local/share/ca-certificates/Yandex/RootCA.crt \
            /usr/local/share/ca-certificates/Yandex/IntermediateCA.crt && \
       update-ca-certificates
   ```

{% endlist %}

_ClickHouse® is a registered trademark of [ClickHouse, Inc](https://clickhouse.com)._