Skip to content

Latest commit

 

History

History
240 lines (176 loc) · 10.3 KB

README.md

File metadata and controls

240 lines (176 loc) · 10.3 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 Javadoc Link
ClickHouse Java Client V2 Maven Central javadoc

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

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.