Skip to content

Latest commit

 

History

History
237 lines (173 loc) · 8.71 KB

README.md

File metadata and controls

237 lines (173 loc) · 8.71 KB
Raw

ClickHouse Java Client & JDBC Driver

Table of Contents

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

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
ClickHouse Java HTTP Client Maven Central
ClickHouse JDBC Driver Maven Central

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.