Connecting to a ClickHouse® cluster from applications
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:
- A local machine with Windows 10 Pro build
19042.1052
- PowerShell:
5.1.19041
Command line tools
To see code examples with the host FQDN filled in, open the cluster page in the management console
clickhouse-client
Before connecting:
-
Connect the DEB repository
ClickHouse®: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
-
Install the dependencies:
sudo apt update && sudo apt install --yes clickhouse-client
-
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
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 a host FQDN, see this guide.
After running the command, enter the user password to complete the connection process.
Once connected to the DBMS, run SELECT @@version;
.
cURL
Linux (Bash)/macOS (Zsh)
curl --header "X-ClickHouse-User: <DB_username>" \
--header "X-ClickHouse-Key: <DB_user_password>" \
'http://<Any_ClickHouse®_host_FQDN>: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 a host FQDN, see this guide.
Windows (PowerShell)
curl.exe `
-H "X-ClickHouse-User: <DB_user_name>" `
-H "X-ClickHouse-Key: <DB_user_password>" `
'http://<FQDN_of_any_ClickHouse®_host>:8123/?database=<DB_name>&query=SELECT+version()'
curl.exe `
-H "X-ClickHouse-User: <DB_user_name>" `
-H "X-ClickHouse-Key: <DB_user_password>" `
'https://<FQDN_of_any_ClickHouse®_host>:8443/?database=<DB_name>&query=SELECT+version()'
To learn how to get a host FQDN, see this guide.
Connecting 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
- JetBrains DataGrip:
You can only use graphical IDEs to connect to public cluster hosts using SSL certificates.
To avoid connection errors, save the certificate
DataGrip
- Create a data source:
- Select File → New → Data Source → ClickHouse®.
- On the General tab:
- 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.
- Click Download to download the connection driver.
- Specify the connection parameters:
- On the SSH/SSL tab:
- Enable the Use SSL setting.
- Specify the path to the directory that contains the file with the downloaded SSL certificate for the connection.
- 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.
- Click OK to save the data source.
DBeaver
- Create a new DB connection:
- In the Database menu, select New connection.
- Select ClickHouse® from the DB list.
- Click Next.
- 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.
- On the Driver properties tab:
- Click Download in a new window with an invitation to download the driver files.
- Specify the SSL connection parameters in the driver property list:
ssl:true
sslrootcert:<path_to_SSL_certificate_file_saved>
- 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.
- Click Ready to save the database connection settings.
Connecting to a cluster from your browser
To run SQL queries from your browser, use:
When connecting from the browser, SQL queries are executed separately without creating a shared session with the ClickHouse® server. Therefore, queries running within the session (for example, USE
or SET
) will have no effect.
Yandex Cloud management console
Warning
The SQL editor built into the management console is designed for a narrow range of data editing tasks. Some parameter values can be replaced by the editor's defaults.
For working with databases, we recommend third-party editors or Yandex WebSQL. To use Yandex WebSQL, click Open on a promo banner and connect to a DB cluster.
To connect to a Managed Service for ClickHouse® cluster, log in to the management console
To allow connections, activate the Access from the management console option when creating a cluster or changing its settings.
For more information, see SQL queries.
ClickHouse® 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 a 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.
Yandex WebSQL service
Note
This feature is in the Preview stage.
Use Yandex WebSQL to connect to a ClickHouse® cluster in Yandex Cloud.
Warning
Yandex WebSQL cannot connect to Managed Service for ClickHouse® clusters with SQL user management enabled. Connect to such a cluster as to an external database.
You can establish connections to managed DB clusters from your Yandex Cloud organization's clouds and folders. If you switch to a different organization, a set of clusters from other clouds and folders will be available to you. Added connections will be available while you are working in the current Yandex Cloud organization.
To create a connection to a managed DB cluster:
- Make sure Access from the management console is enabled in the cluster settings.
- In Yandex WebSQL, go to the Connection manager section and click
in the top-right corner. - Specify the connection parameters:
- Cloud: Select a cloud.
- Folder: Select the folder where you created the database cluster.
- Cluster: Select the cluster.
- Click Connect to connect to the selected cluster.
To build a query:
-
In the Connection manager, select a database, table, or image.
-
In the data panel, you will see a form with the default query:
SELECT * FROM <table_name> LIMIT 10;
-
Use this query or edit it. The interface will suggest relevant parts of the SQL query and highlight errors.
-
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):- 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 (
Before 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:
# Connect 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 dependencies.
apt-get update && \
apt-get install wget clickhouse-client --yes && \
# Upload a 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
# Connect 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 dependencies.
apt-get update && \
apt-get install wget clickhouse-client --yes && \
# Upload a 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 && \
# 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
ClickHouse® is a registered trademark of ClickHouse, Inc