ClickHouse - How to connect to a ClickHouse cluster with CLI

Knowledge Base

KB0075111

ClickHouse - How to connect to a ClickHouse cluster with CLI


Icons/System/eye-open Created with Sketch. 5 Views 25.02.2026 ClickHouse

Objective

ClickHouse is an open-source, columnar analytical database system designed for real-time processing of massive data volumes, providing high performance, scalability, and low latency.

This guide explains how to connect to a ClickHouse cluster using the CLI.

Requirements

Instructions

Verify that your public IP address is part of the "Authorised IPs" defined for this ClickHouse service.

Check also that the user has the required ACLs for the target databases.

Downloading server and user certificates

To connect to the ClickHouse service, you need server and user certificates.

  • Server certificate: The server Certificate Authority (CA) certificate can be downloaded from the Dashboard tab.
  • User certificate and access key: The user certificate and the user access key can be downloaded from the Users tab.

Installing the ClickHouse CLI

As part of the official ClickHouse installation, you will have access to several tools, including the standard clickhouse-client CLI. For details, see the official ClickHouse Client documentation.

ClickHouse configuration file

You can configure the ClickHouse Client using an XML or YAML file to simplify connection. The client searches for configuration files in the following order:

  1. A file specified with -c / --config / --config-file.
  2. ./clickhouse-client.[xml|yaml|yml].
  3. $XDG_CONFIG_HOME/clickhouse/config.[xml|yaml|yml] (or ~/.config/clickhouse/config.[xml|yaml|yml] if XDG_CONFIG_HOME is not set).
  4. ~/.clickhouse-client/config.[xml|yaml|yml].
  5. /etc/clickhouse-client/config.[xml|yaml|yml].
Example XML configuration

Create a file named clickhouse-client.xml with the following content:

<config>
    <user>default</user>
    <password>your_password</password>
    <secure>true</secure>

    <openSSL>
        <client>
            <caConfig>/home/user/clickhouse/ca.pem</caConfig>
        </client>
    </openSSL>

    <connections_credentials>
        <connection>
            <name>default</name>
            <hostname>clickhouse-12345.cluster.database.cloud.ovh.net</hostname>
            <port>9440</port>
        </connection>
    </connections_credentials>
</config>

For more information, see the sample official configuration file.

Example YAML configuration

Create a file named clickhouse-client.yml with the following minimal content:

user: default
password: 'your_password'
secure: true
openSSL:
  client:
    caConfig: '/home/user/clickhouse/ca.pem'

Change these values according to your own cluster configuration.

Using the ClickHouse CLI

Inserting data into ClickHouse

For this first example, let's insert a test row into the my_table table in the test_db database.

clickhouse-client --query "INSERT INTO test_db.my_table (id, message) VALUES (1, 'test-message-content')"

Querying data from ClickHouse

Retrieve all the data from the my_table table in the test_db database:

clickhouse-client --query "SELECT * FROM test_db.my_table"

Go further

We would love to help answer questions and appreciate any feedback you may have.

If you need training or technical assistance to implement our solutions, contact your sales representative or click on this link to get a quote and ask our Professional Services experts for a custom analysis of your project.

Are you on Discord? Connect to our channel at https://discord.gg/ovhcloud and interact directly with the team that builds our Analytics service!

Join our community of users.

Related articles