ClickHouse/clickhouse-java

ClickHouse Java Clients & JDBC Driver https://clickhouse.com

Download

Step 1. Add the JitPack repository to your build file

Add it in your root build.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}
	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.yandex:clickhouse-jdbc:0.3.2-test3'
	}
	<dependency>
	    <groupId>com.github.yandex</groupId>
	    <artifactId>clickhouse-jdbc</artifactId>
	    <version>0.3.2-test3</version>
	</dependency>

                            
    libraryDependencies += "com.github.yandex" % "clickhouse-jdbc" % "0.3.2-test3"
        
        

                            
    :dependencies [[com.github.yandex/clickhouse-jdbc "0.3.2-test3"]]

Readme

<div align="center"> <p> <a href="https://github.com/ClickHouse/clickhouse-java/releases/latest"><img src="https://img.shields.io/github/v/release/ClickHouse/clickhouse-java?include_prereleases&label=Latest%20Release"/></a> <a href="https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/"><img src="https://img.shields.io/nexus/s/com.clickhouse/clickhouse-java?label=Nightly%20Build&server=https%3A%2F%2Fs01.oss.sonatype.org"/></a> <a href="https://github.com/ClickHouse/clickhouse-java/milestone/4"><img src="https://img.shields.io/github/milestones/progress-percent/ClickHouse/clickhouse-java/16"/></a> <a href="https://github.com/ClickHouse/clickhouse-java/releases/"><img src="https://img.shields.io/github/downloads/ClickHouse/clickhouse-java/latest/total"/></a> </p> <p><img src="https://github.com/ClickHouse/clickhouse-js/blob/a332672bfb70d54dfd27ae1f8f5169a6ffeea780/.static/logo.svg" width="200px" align="center"></p> <h1>ClickHouse Java Client & JDBC Driver</h1> </div>

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.