Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
  • Blog
  • Pricing
  • Documentation
Yandex project
© 2025 Yandex.Cloud LLC
Yandex Managed Service for ClickHouse®
  • Getting started
    • All guides
      • Pre-configuration
      • FQDNs of hosts
      • Connecting from applications
      • Code snippets
  • Access management
  • Terraform reference
  • Yandex Monitoring metrics
  • Audit Trails events
  • Public materials
  • Release notes

In this article:

  • Command line tools
  • clickhouse-client
  • cURL
  • Connecting from graphical IDEs
  • DataGrip
  • DBeaver
  • Connecting to a cluster from your browser
  • ClickHouse® built-in SQL editor
  • Yandex WebSQL service
  • Before you connect from a Docker container
  1. Step-by-step guides
  2. Connection
  3. Connecting from applications

Connecting to a ClickHouse® cluster from applications

Written by
Yandex Cloud
Updated at May 5, 2025
  • Command line tools
    • clickhouse-client
    • cURL
  • Connecting from graphical IDEs
    • DataGrip
    • DBeaver
  • Connecting to a cluster from your browser
    • ClickHouse® built-in SQL editor
    • Yandex WebSQL service
  • Before you connect from a Docker container

This section provides settings for connecting to Managed Service for ClickHouse® cluster hosts using command line tools, graphical IDEs, browser, and Docker container. To learn how to connect from your application code, see Code examples.

You can connect to public ClickHouse® cluster hosts only if you use SSL certificates. The examples below assume that RootCA.crt and IntermediateCA.crt certificates are:

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

Connecting without SSL certificates is only supported for non-public hosts. For connections to the database, traffic inside the virtual network is not encrypted in this case.

Before connecting, configure security groups for the cluster, if required.

The examples for Linux were tested in the following environment:

  • Yandex Cloud virtual machine 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 toolsCommand line tools

To see code examples with the host FQDN filled in, open the cluster page in the management console and click Connect.

clickhouse-clientclickhouse-client

Before connecting:

  1. Connect the ClickHouse® DEB repository:

    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
    
  2. Install the dependencies:

    sudo apt update && sudo apt install --yes clickhouse-client
    
  3. Download the configuration file for clickhouse-client:

    mkdir -p ~/.clickhouse-client && \
    wget "https://storage.yandexcloud.net/doc-files/clickhouse-client.conf.example" \
      --output-document ~/.clickhouse-client/config.xml
    
Connecting without SSL
Connecting via SSL
clickhouse-client --host <FQDN_of_any_ClickHouse®_host> \
                  --user <username> \
                  --database <DB_name> \
                  --port 9000 \
                  --ask-password
clickhouse-client --host <FQDN_of_any_ClickHouse®_host> \
                  --secure \
                  --user <username> \
                  --database <DB_name> \
                  --port 9440 \
                  --ask-password

To learn how to get host FQDN, see this guide.

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

After connecting to the DBMS, run the SELECT version(); command.

cURLcURL

Linux (Bash)/macOS (Zsh)Linux (Bash)/macOS (Zsh)

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

To learn how to get host FQDN, see this guide.

Windows (PowerShell)Windows (PowerShell)

Connecting without SSL
Connecting via SSL
curl.exe `
    --header "X-ClickHouse-User: <DB_username>" `
    --header "X-ClickHouse-Key: <DB_user_password>" `
    'http://<FQDN_of_any_ClickHouse®_host>:8123/?database=<DB_name>&query=SELECT+version()'
curl.exe `
    --header "X-ClickHouse-User: <DB_username>" `
    --header "X-ClickHouse-Key: <DB_user_password>" `
    'https://<FQDN_of_any_ClickHouse®_host>:8443/?database=<DB_name>&query=SELECT+version()'

To learn how to get host FQDN, see this guide.

Connecting from graphical IDEsConnecting from graphical IDEs

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

You can only use graphical IDEs to connect to public cluster hosts using an SSL certificate.

To avoid connection errors, save the certificate to a local folder that does not require administrator rights to access.

DataGripDataGrip

  1. Create a data source:
    1. Select File → New → Data Source → ClickHouse®.
    2. On the General tab:
      1. Specify the connection parameters:
        • Host: Any ClickHouse® host FQDN or a special FQDN.
        • Port: 8443.
        • User, Password: DB user's name and password.
        • Database: Name of the DB to connect to.
      2. Click Download to download the connection driver.
    3. On the SSH/SSL tab:
      1. Enable the Use SSL setting.
      2. Specify the path to the directory that contains the file with the downloaded SSL certificate for the connection.
  2. Click Test Connection to test the connection. If the connection is successful, you will see the connection status and information about the DBMS and driver.
  3. Click OK to save the data source.

DBeaverDBeaver

  1. Create a new DB connection:
    1. In the Database menu, select New connection.
    2. Select ClickHouse® from the DB list.
    3. Click Next.
    4. Specify the connection parameters on the Main tab:
      • Host: FQDN of any ClickHouse® host or a special FQDN.
      • Port: 8443.
      • DB/Schema: Name of the DB to connect to.
      • Under Authentication, specify the DB user's name and password.
    5. On the Driver properties tab:
      1. Click Download in a new window with an invitation to download the driver files.
      2. Specify the SSL connection parameters in the driver property list:
        • ssl:true
        • sslrootcert:<path_to_saved_SSL_certificate_file>.
  2. Click Test connection ... to test the connection. If the connection is successful, you will see the connection status and information about the DBMS and driver.
  3. Click Ready to save the database connection settings.

Connecting to a cluster from your browserConnecting to a cluster from your browser

To run SQL queries from your browser, use:

  • ClickHouse® built-in SQL editor

  • Yandex WebSQL service

ClickHouse® built-in SQL editorClickHouse® built-in SQL editor

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

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

You can only connect to public cluster hosts. To learn how to get host FQDN, see this guide.

To connect to a cluster by selecting an available host automatically, use the following URL:

  • https://c-<cluster_ID>.rw.mdb.yandexcloud.net:8443/play: To connect to the available cluster host.
  • https://<shard_name>.c-<cluster_ID>.rw.mdb.yandexcloud.net:8443/play: To connect to the available shard host.

To make a query to the database, specify the username and password in the upper-right corner.

When connecting 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, will have no effect.

Yandex WebSQL serviceYandex WebSQL service

Note

This feature is at the Preview stage.

Use Yandex WebSQL to connect to a ClickHouse® cluster in Yandex Cloud.

Before creating a connection, make sure that you have selected the required folder. If you have access to PostgreSQL, ClickHouse®, MySQL®, Valkey™, or MongoDB 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

Yandex Managed Service for Trino is at the Preview 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.

Connections to clusters created in Yandex MetaData Hub Connection Manager will also be displayed automatically provided you have roles to manage these connections in Connection Manager.

To create a connection to a managed database cluster:

  1. Make sure WebSQL access is enabled in the cluster settings.
  2. Open Yandex WebSQL Connections.
  3. Under Connections, click .
  4. Name the connection.
  5. In the Database type field, select the database you need: PostgreSQL, ClickHouse®, MySQL®, Valkey™, or MongoDB.
  6. In the Cluster folder field, select the folder hosting the required cluster.
  7. In the Cluster field, select the managed database cluster you want to connect to.
  8. Specify the Username you will use to connect to cluster databases.
  9. Enter the user Password.
  10. 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.
  11. Click Create.

To build a query:

  1. Under Connections, select a database, table, or image.

  2. In the data panel, you will see a form with the default query:

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

  4. 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 to see the full list):

Windows/Linux
macOS
  • Show suggestions: Ctrl + I , Ctrl + Space.
  • Comment out a line: Ctrl + /.
  • Run a query: Ctrl + Enter.
  • Show suggestions: ⌘ + I , ⌃ + Space.
  • Comment out a line: ⌘ + /.
  • Run a query: ⌘ + ⏎.

Click Open Command Palette to view a complete list of available commands and their corresponding keyboard shortcuts.

Before you connect from a Docker containerBefore you connect from a Docker container

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

Connecting without SSL
Connecting via SSL
# Connecting 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 && \
    # Installing dependencies
    apt-get update && \
    apt-get install wget clickhouse-client --yes && \
    # Downloading the configuration file for clickhouse-client
    mkdir --parents ~/.clickhouse-client && \
    wget "https://storage.yandexcloud.net/doc-files/clickhouse-client.conf.example" \
         --output-document ~/.clickhouse-client/config.xml
# Connecting 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 && \
    # Installing dependencies
    apt-get update && \
    apt-get install wget clickhouse-client --yes && \
    # Downloading the configuration file for clickhouse-client
    mkdir --parents ~/.clickhouse-client && \
    wget "https://storage.yandexcloud.net/doc-files/clickhouse-client.conf.example" \
         --output-document ~/.clickhouse-client/config.xml && \
    # Getting 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

ClickHouse® is a registered trademark of ClickHouse, Inc.

Was the article helpful?

Previous
FQDNs of hosts
Next
Code snippets
Yandex project
© 2025 Yandex.Cloud LLC