Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ClickHouse/clickhouse-java
ClickHouse Java Clients & JDBC Driver
https://github.com/ClickHouse/clickhouse-java
clickhouse java-client jdbc jdbc-driver
Last synced: 30 days ago
JSON representation
ClickHouse Java Clients & JDBC Driver
- Host: GitHub
- URL: https://github.com/ClickHouse/clickhouse-java
- Owner: ClickHouse
- License: apache-2.0
- Created: 2016-07-15T12:48:27.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-11-08T18:03:02.000Z (about 1 month ago)
- Last Synced: 2024-11-11T08:54:22.812Z (about 1 month ago)
- Topics: clickhouse, java-client, jdbc, jdbc-driver
- Language: Java
- Homepage: https://clickhouse.com
- Size: 7.62 MB
- Stars: 1,447
- Watchers: 54
- Forks: 534
- Open Issues: 274
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-clickhouse - ClickHouse/clickhouse-java - ClickHouse Java Clients and JDBC Driver for efficient database interaction. (Language bindings / Java)
README
ClickHouse Java Client & JDBC Driver
Table of Contents
* [About The project](#about-the-project)
* [Important Updates](#important-updates)
* [Installation](#installation)
* [Client V2](#client-v2)
* [Artifacts](#artifacts)
* [Features](#features)
* [Examples](#examples)
* [Client V1](#client-v1)
* [Artifacts](#artifacts-1)
* [Features](#features-1)
* [Examples](#examples-1)
* [Documentation](#documentation)
* [Contributing](#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 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 | [](https://mvnrepository.com/artifact/com.clickhouse/client-v2) | [](https://javadoc.io/doc/com.clickhouse/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](../../tree/main/examples/client-v2)
[Spring Demo Service](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-service)
Minimal client setup:
```java
String endpoint = "https://:8443/"
Client client = new Client.Builder()
.addEndpoint(endpoint)
.setUsername(user)
.setPassword(password)
.setDefaultDatabase(database)
.build();
```
Insert POJOs example:
```java
client.register(
ArticleViewEvent.class, // your DTO class
client.getTableSchema(TABLE_NAME)); // corresponding table
List events = // load data
try (InsertResponse response = client.insert(TABLE_NAME, events).get(1, TimeUnit.SECONDS)) {
// process results
}
```
Query results reader example:
```java
// 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:
```java
// 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:
```java
Client client = new Client.Builder()
.addEndpoint("https://" + dbHost + ":8443")
.setUsername("default")
.setPassword("")
.build(),
```
Connecting to a database instance with self-signed certificate:
```java
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 | [](https://mvnrepository.com/artifact/com.clickhouse/clickhouse-client) | [](https://javadoc.io/doc/com.clickhouse/clickhouse-client) |
| ClickHouse Java HTTP Client | [](https://mvnrepository.com/artifact/com.clickhouse/clickhouse-http-client) | [](https://javadoc.io/doc/com.clickhouse/clickhouse-http-client) |
| ClickHouse JDBC Driver | [](https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc) | [](https://javadoc.io/doc/com.clickhouse/clickhouse-jdbc) |
| ClickHouse R2DBC Driver | [](https://mvnrepository.com/artifact/com.clickhouse/clickhouse-r2dbc) | [](https://javadoc.io/doc/com.clickhouse/clickhouse-r2dbc) |
| ClickHouse gRPC Driver | [](https://mvnrepository.com/artifact/com.clickhouse/clickhouse-grpc-client) | [](https://javadoc.io/doc/com.clickhouse/clickhouse-grpc-client) | [](https://javadoc.io/doc/com.clickhouse/clickhouse-grpc-client) |
### 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](../../tree/main/examples/client)
See [JDBC examples](../../tree/main/examples/jdbc)
## Compatibility
- All projects in this repo are tested with all [active LTS versions](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) of ClickHouse.
- [Support policy](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md#security-change-log-and-support)
- 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](https://clickhouse.com/docs/en/integrations/language-clients/java/client)
[JDBC Docs :: ClickHouse website](https://clickhouse.com/docs/en/integrations/language-clients/java/jdbc).
## Contributing
Please see our [contributing guide](./CONTRIBUTING.md).