ClickHouse Java Client & JDBC Driver

Table of Contents

• About The project
• Important Updates
• Installation
• Client V2
  • Artifacts
  • Features
  • Examples
• Client V1
  • Artifacts
  • Features
  • Examples
• Documentation
• Contributing

About the Project

This is official Java Client and JDBC for ClickHouse Database (https://github.com/ClickHouse/Clickhouse). Java Client is the core component and provides API to interact with the database. In 2023 this component and its API was refactored into a new component client-v2. Both version are available but older one will be deprecated soon. However it will receive security and critical bug fixes. New client-v2 has stable API and we are working on performance and feature parity to make it a production ready.
JDBC driver component is an implementation of JDBC API. It uses Java Client API to interact with the database server.

Benefits of using Client-V2:

• Stable API.
• Minimal functionality is implemented
  • SSL & mTLS support
  • RowBinary* formats support for reading
  • Proxy support
  • HTTP protocol
• New Insert API that accepts a list of POJOs
• New Query API that returns a list of GenericRecords that cant be used as DTOs
• Native format reader
• Performance improvements
  • Less number of internal buffers compare to the old client
  • More configuration for performance tuning
  • Less object allocation
• Upcoming new features

Old client still be used when:

• using JDBC driver ( we are working on its refactoring )

Important

Upcomming deprecations:

Component	Version	Comment
ClickHouse Java v1	TBC	We'll be deprecating Java v1 in 2025
ClickHouse CLI Client (Java)	0.7.0	Please use clickhouse-client (see https://clickhouse.com/docs/en/interfaces/cli#clickhouse-client)
ClickHouse GRPC Client	0.7.0	Please use the ClickHouse http client instead. GRPC protos still available https://github.com/ClickHouse/ClickHouse/tree/master/src/Server/grpc_protos

Installation

Releases: Maven Central (web site https://mvnrepository.com/artifact/com.clickhouse)

Nightly Builds: https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/

Client V2

Artifacts

Component	Maven Central Link	Javadoc Link
ClickHouse Java Client V2

Compatibility

ClickHouse Version	Client Version	Comment
Server >= 23.0	0.6.2

Features

• Http API for ClickHouse support
• Bi-directional Compression
  • LZ4
• Insert from POJO (data is provided as list of java objects)
• Query formats support:
  • RowBinary readers
  • Native format reader
• Apache HTTP Client as HTTP client
  • Connection pooling
  • Failures on retry
• SSL support
• Cloud support
• Proxy support

Examples

Begin-with Usage Examples

Spring Demo Service

Minimal client setup:

String endpoint = "https://<db-instance hostname>:8443/"
Client client = new Client.Builder()
        .addEndpoint(endpoint)
        .setUsername(user)
        .setPassword(password)
        .setDefaultDatabase(database)
        .build();

Insert POJOs example:

client.register(
  ArticleViewEvent.class, // your DTO class  
  client.getTableSchema(TABLE_NAME)); // corresponding table

List<ArticleViewEvents> events = // load data 

try (InsertResponse response = client.insert(TABLE_NAME, events).get(1, TimeUnit.SECONDS)) {
  // process results 
}

Query results reader example:

// Default format is RowBinaryWithNamesAndTypesFormatReader so reader have all information about columns
try (QueryResponse response = client.query(sql).get(3, TimeUnit.SECONDS);) {

    // Create a reader to access the data in a convenient way
    ClickHouseBinaryFormatReader reader = new RowBinaryWithNamesAndTypesFormatReader(response.getInputStream(),
            response.getSettings());

    while (reader.hasNext()) {
        reader.next(); // Read the next record from stream and parse it

        double id = reader.getDouble("id");
        String title = reader.getString("title");
        String url = reader.getString("url");

        // result processing 
    }
}

Query result as list of object example:

// Data is read completely and returned as list of objects.
client.queryAll(sql).forEach(row -> {
              double id = row.getDouble("id");
              String title = row.getString("title");
              String url = row.getString("url");

              // result processing
            });

Connecting to the ClickHouse Cloud instance or DB server having not a self-signed certificate:

Client client = new Client.Builder()
  .addEndpoint("https://" + dbHost + ":8443")
  .setUsername("default")
  .setPassword("")
  .build(),

Connecting to a database instance with self-signed certificate:

Client client = new Client.Builder()
  .addEndpoint("https://" + dbHost + ":8443")
  .setUsername("default")
  .setPassword("")
  .setRootCertificate("localhost.crt") // path to the CA certificate
  //.setClientKey("user.key") // user private key 
  //.setClientCertificate("user.crt") // user public certificate
  .build(),

Client V1

Artifacts

Component	Maven Central Link	Javadoc Link
ClickHouse Java Unified Client
ClickHouse Java HTTP Client
ClickHouse JDBC Driver
ClickHouse R2DBC Driver
ClickHouse gRPC Driver

Features

• Http API for ClickHouse support
• Bi-directional Compression
  • LZ4
• Apache HTTP Client as HTTP client
  • Connection pooling
  • Failures on retry
• SSL & mTLS support
• Cloud support
• Proxy support

Examples

See java client examples

See JDBC examples

Compatibility

• All projects in this repo are tested with all active LTS versions of ClickHouse.
• Support policy
• We recommend to upgrade client continuously to not miss security fixes and new improvements
  • If you have an issue with migration - create and issue and we will respond!

Documentation

Java Client V1 Docs :: ClickHouse website

JDBC Docs :: ClickHouse website.

Contributing

Please see our contributing guide.