Skip to main content
Version: 5.2

ClickHouse

Choosing a Configuration Type​

To specify the configuration type, you need to select one of the tiles displayed on the page. In this case, select the Clickhouse tile.

Important!

Once saved, the configuration type cannot be changed.

Entering Connection Information​

Further configuration details are entered in the Enter configuration information section. Fields marked with a red asterisk are mandatory. If any field contains incorrect data, the configuration will not be saved, and an error message will appear next to the field with the issue. Follow these steps to input connection information:

  1. Enter the configuration name in the Configuration Name input field. Only Latin letters or numbers in CamelCase style are allowed
  2. Then, select a JDBC driver in the Upload Driver field. If the required driver is not listed, you can upload your own by clicking the Upload File button below the input field. A modal window will open where you need to select a JDBC driver with a .jar extension. Other file types will not be accepted
  3. The "Driver Class Name" field is filled automatically. If the JDBC driver contains multiple classes, you can specify the required class. Only Latin letters or numbers are allowed in this field
Recommended JDBC Driver

For connecting to ClickHouse, it is recommended to use the official driver com.clickhouse:clickhouse-jdbc in the *-all-dependencies.jar artifact variant. Such JAR files already contain all necessary dependencies and do not require additional library installation.

A suitable version can be found in the central Maven repository (section com.clickhouse / clickhouse-jdbc) or downloaded directly via a link like:

https://repo1.maven.org/maven2/com/clickhouse/clickhouse-jdbc/<version>/clickhouse-jdbc-<version>-all-dependencies.jar

Note!

By default, the connection string field is auto-populated based on the JDBC driver class. For ClickHouse, the following classes are supported: cc.blynk.clickhouse.ClickHouseDriver, com.clickhouse.jdbc.ClickHouseDriver. If the driver uses different classes, the connection string will still be auto-filled, but you should verify the Connection String field for accuracy. Otherwise, switch to advanced mode and correct it manually.

  1. Enter the host in the "Host" field. Examples include 172.168.0.1 or yourhost
  2. Enter the port in the "Port" field. Only numbers are allowed
  3. If needed, you can specify the default database name in the "Default Database" field
  4. If your connection requires SSL validation, enable the "SSL Validation" field. A warning about saving data in the keystore will appear, as shown in the illustration

ClickHouse Keystore Warning

You can then enable host name verification and specify the path to the trust store in the Trust Store Path field. Only paths like /my_path/to/trust-store/ are allowed.

Important!

SSL parameters are set for the official ClickHouse driver. If you use a different driver, switch to advanced mode and enter the required parameters manually.

  1. If your connection requires user and password authentication or just a username, fill in the respective "User" and "Password" fields

  2. To test the connection, click the "Test Connection" button. If the ClickHouse connection is successful, the following message will appear:

Successful Connection

Otherwise, an error message will be displayed, such as:

Connection Error

Note

The article shows an example error message. The actual error may vary.

The configuration can be saved with connection errors. However, it will not be saved if there are format errors or empty mandatory fields.

Preparing Trust Store and Keystore for SSL Connections​

This section describes how to prepare a trust store with certificates for verifying the ClickHouse server and how to pass the trust store password to a secure parameter storage (keystore).

Purpose of the Trust Store​

A trust store is a file-based storage of trusted certificates (usually in JKS or PKCS12 format) used by the JVM to verify server authenticity.

The trust store must contain the certificate of the Certification Authority (CA) that signed the ClickHouse server certificates. If a self-signed certificate is used for ClickHouse, that very certificate should be added to the trust store.

Creating and Populating the Trust Store​

  1. Obtain the CA certificate file or the ClickHouse self-signed certificate in PEM/CRT format, e.g., clickhouse-ca.pem

  2. Copy this file to the node from which the connection to ClickHouse is made (the node where the component using the JDBC connection runs)

  3. Create a directory for the trust store if it doesn't already exist (e.g., the application configuration directory).

  4. Create a new trust store and import the certificate into it using the keytool utility:

    keytool -importcert      -file clickhouse-ca.pem      -alias clickhouse-ca      -keystore /path/to/clickhouse-truststore.jks      -storetype JKS      -storepass <truststore_password>

    On the first run, keytool will prompt you to create a new storage file and request a password. This password must be remembered—it will be used when configuring the keystore.

  5. Restrict access to the trust store file so that only the system user running the application can access it:

    chown <user>:<group> /path/to/clickhouse-truststore.jks
    chmod 600 /path/to/clickhouse-truststore.jks

  6. In the ClickHouse connection configuration interface, specify the full path to the created file in the Trust store path field

Adding the Trust Store Password to the Keystore​

For security, the trust store password is not stored in plain text in the configuration. Instead, it should be saved in a secure parameter storage (keystore).

After enabling the SSL validation option and filling in the Trust store path field, a yellow warning appears at the bottom of the form, displaying the keystore variable name into which the password must be saved. The name has the format:

sme.sa.trust_store.password.<ConfigurationName>

General procedure:

  1. Click Save changes in the connection configuration

  2. Refresh the page to ensure the warning and keystore variable name are displayed correctly

  3. On each node where connections to ClickHouse are made, execute the command to add an entry to the keystore using the specified variable name. For OpenSearch-based platforms, this is done using the opensearch-keystore utility (the path and command may vary depending on the distribution):

    opensearch-keystore add sme.sa.trust_store.password.<ConfigurationName>

  4. In interactive mode, the utility will request a value. Enter the password used when creating the trust store (<truststore_password>)

  5. Repeat the operation on all cluster nodes that require access to ClickHouse via this configuration

Important!
  • the variable name for the keystore must be taken exactly from the yellow warning in the configuration interface
  • if you change the configuration name, the variable name will also change, and the password will need to be added again
  • after modifying the keystore, it is recommended to restart the relevant services so the new parameters are picked up

Editing Configuration Features​

The configuration is edited following the same rules as it is created. Fields can be modified in any arbitrary order, while maintaining the overall logic: first, select the correct JDBC driver; then, specify the connection parameters (host, port, database); after that, enable SSL if necessary, configure the trust store path, and add the password to the keystore. After saving the changes and successfully verifying the connection, the configuration is ready for use.