Awesome

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:

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
ClickHouse Java Client V2

Compatibility

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
ClickHouse Java HTTP Client
ClickHouse JDBC 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.