Skip to content

JDBC Driver

Connect to Hydrolix from a Java application using the ClickHouse JDBC driver. This page describes how to add the driver to your project, build the connection URL, and run a sample query.

If you want to use a graphical SQL client instead of writing Java code, see the DBeaver page, which uses the same underlying driver.

Prerequisites⚓︎

  • Java 11 or later installed.
  • A build tool (for example, Maven or Gradle), or the driver JAR on your classpath.
  • Your Hydrolix cluster hostname and a bearer token for your account. To get a token, see Acquire authorization token.

Add the ClickHouse JDBC driver to your project⚓︎

Add the clickhouse-jdbc dependency to your build configuration. Check the ClickHouse JDBC releases for the latest version. The driver uses SLF4J for logging, so add an SLF4J binding too. The example uses slf4j-nop, which discards log messages; replace it with your project's preferred logging provider, for example Logback or Log4j 2.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.9.8</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-nop</artifactId>
    <version>2.0.13</version>
</dependency>

1
2
implementation 'com.clickhouse:clickhouse-jdbc:0.9.8'
implementation 'org.slf4j:slf4j-nop:2.0.13'

Build the JDBC connection URL⚓︎

The JDBC URL uses the jdbc:ch scheme, followed by the https protocol, hostname, and port:

JDBC URL Format
1
jdbc:ch:https://${HDX_HOSTNAME}:8088
  • Set HDX_HOSTNAME to your cluster's fully qualified hostname, for example hostname.hydrolix.live.
  • Use the standard ClickHouse HTTP port 8088, or your cluster's configured clickhouse_http_port.
  • Use the https protocol. Only use http if your cluster is configured to disable TLS.

Configure an authorization token in the bearer_token driver property. Load the token from an environment variable or secret manager so it doesn't appear in source code.

Open the connection and run a query⚓︎

The hydro.logs table contains log event data from the local cluster and is always present. This example opens a connection, runs a SELECT COUNT() against hydro.logs, and prints the result.

Query Hydro Logs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.Properties;

public class HydrolixJdbcExample {
    public static void main(String[] args) throws SQLException {
        String host = System.getenv("HDX_HOSTNAME");
        String token = System.getenv("HDX_TOKEN");
        if (host == null || token == null) {
            throw new IllegalStateException("Set HDX_HOSTNAME and HDX_TOKEN.");
        }

        String url = "jdbc:ch:https://" + host + ":8088";

        Properties properties = new Properties();
        properties.setProperty("bearer_token", token);

        String sql = "SELECT COUNT() FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 24 HOUR";

        try (Connection conn = DriverManager.getConnection(url, properties);
             Statement stmt = conn.createStatement();
             ResultSet rs = stmt.executeQuery(sql)) {
            if (rs.next()) {
                System.out.println("Log events in the last 24 hours: " + rs.getLong(1));
            }
        }
    }
}

Run the example with your cluster hostname and bearer token in environment variables:

1
2
3
export HDX_HOSTNAME=mycluster.hydrolix.live
export HDX_TOKEN=eyJhbGciOi...
mvn exec:java -Dexec.mainClass=HydrolixJdbcExample

1
2
3
export HDX_HOSTNAME=mycluster.hydrolix.live
export HDX_TOKEN=eyJhbGciOi...
gradle run

With Gradle, the run task requires the application plugin with mainClass = 'HydrolixJdbcExample' configured in your build.gradle.

Example Output
1
Log events in the last 24 hours: 12759141

Troubleshooting⚓︎

Connection refused or connection timeout⚓︎

The client can't reach the cluster on port 8088. Two different causes produce similar network-level errors, so check both:

  1. Client IP isn't on the cluster's allowlist. Verify that you've allowed inbound access to your cluster.
  2. Port 8088 isn't exposed on the cluster. By default, Hydrolix clusters run a ClickHouse HTTP server on port 8088, but the server doesn't run if the cluster configuration contains disable_traefik_clickhouse_http_port: true. Check with your cluster administrator whether this tunable is set. If it's true, the driver can't connect on port 8088 until the cluster exposes that port again.

SLF4J warns "No SLF4J providers were found"⚓︎

The driver logs through SLF4J and needs an SLF4J binding on the classpath. Add slf4j-nop (to discard log messages) or another binding like Logback or Log4j 2. The warning is non-fatal: queries still work.

See also⚓︎