From a5d5be5b8ceaf5d6ee61663b0375e636a52a539c Mon Sep 17 00:00:00 2001 From: Zhichun Wu Date: Tue, 30 Aug 2022 21:51:02 +0800 Subject: [PATCH 1/2] Update readme and examples --- README.md | 107 +++++++++++++++++++++++++----------------- examples/grpc/pom.xml | 10 +++- examples/jdbc/pom.xml | 8 ++++ 3 files changed, 80 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index c075741f2..39cb5f2f1 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,9 @@ # ClickHouse Java Client & JDBC Driver -[![GitHub release (latest SemVer including pre-releases)](https://img.shields.io/github/v/release/ClickHouse/clickhouse-jdbc?include_prereleases)](https://github.com/ClickHouse/clickhouse-jdbc/releases/) ![Build Status(https://github.com/ClickHouse/clickhouse-jdbc/workflows/Build/badge.svg)](https://github.com/ClickHouse/clickhouse-jdbc/workflows/Build/badge.svg) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ClickHouse_clickhouse-jdbc&metric=coverage)](https://sonarcloud.io/dashboard?id=ClickHouse_clickhouse-jdbc) +[![GitHub release (latest SemVer including pre-releases)](https://img.shields.io/github/v/release/ClickHouse/clickhouse-jdbc?style=plastic&include_prereleases&label=Latest%20Release)](https://github.com/ClickHouse/clickhouse-jdbc/releases/) [![Sonatype Nexus (Snapshots)](https://img.shields.io/nexus/s/com.clickhouse/clickhouse-jdbc?style=plastic&label=Nightly%20Build&server=https%3A%2F%2Fs01.oss.sonatype.org)](https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/) ![GitHub milestone](https://img.shields.io/github/milestones/progress-percent/ClickHouse/clickhouse-jdbc/6?style=social) Java client and JDBC driver for ClickHouse. Java client is async, lightweight, and low-overhead library for ClickHouse; while JDBC driver is built on top of the Java client with more dependencies and extensions for JDBC-compliance. - -Java 8 or higher is required in order to use Java client([clickhouse-client](https://github.com/ClickHouse/clickhouse-jdbc/tree/master/clickhouse-client)) and/or JDBC driver([clickhouse-jdbc](https://github.com/ClickHouse/clickhouse-jdbc/tree/master/clickhouse-jdbc)). In addition, starting from 0.3.2, JDBC driver only works with ClickHouse 20.7 or above, so please consider to either downgrade the driver to 0.3.1-patch or upgrade server to one of [active releases](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease). +Java 8 or higher is required to use Java client([clickhouse-client](https://github.com/ClickHouse/clickhouse-jdbc/tree/master/clickhouse-client)) and/or JDBC driver([clickhouse-jdbc](https://github.com/ClickHouse/clickhouse-jdbc/tree/master/clickhouse-jdbc)). In addition, starting from 0.3.2, JDBC driver only works with ClickHouse 20.7+, so please consider to either upgrade server to one of [active releases](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) or downgrade the driver to 0.3.1-patch(not recommended). --- @@ -15,47 +14,64 @@ Maven groupId `ru.yandex.clickhouse` and legacy JDBC driver `ru.yandex.clickhous Please use new groupId `com.clickhouse` and driver `com.clickhouse.jdbc.ClickHouseDriver` instead. It's highly recommended to upgrade to 0.3.2+ now for improved performance and stability. ![image](https://user-images.githubusercontent.com/4270380/154429324-631f718d-9277-4522-b60d-13f87b2e6c31.png) -Note: in general, the new driver(v0.3.2) is a few times faster with less memory usage. More information can be found at [here](https://github.com/ClickHouse/clickhouse-jdbc/issues/768). +Note: in general, the new driver(v0.3.2+) is a few times faster with less memory usage. More information can be found at [here](https://github.com/ClickHouse/clickhouse-jdbc/issues/768). --- ## Features -| Category | Feature | Supported | Remark | -| ----------------- | -------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| API | [JDBC](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) | :white_check_mark: | | -| | [R2DBC](https://r2dbc.io/) | :x: | will be supported in 0.3.3 | -| Protocol | [HTTP](https://clickhouse.com/docs/en/interfaces/http/) | :white_check_mark: | recommended, defaults to `java.net.HttpURLConnection` and can be changed to `java.net.http.HttpClient`(faster but less stable) | -| | [gRPC](https://clickhouse.com/docs/en/interfaces/grpc/) | :white_check_mark: | still experimental, works with 22.3+, known to has [issue](https://github.com/ClickHouse/ClickHouse/issues/28671#issuecomment-1087049993) when using LZ4 compression | -| | [TCP/Native](https://clickhouse.com/docs/en/interfaces/tcp/) | :white_check_mark: | `clickhouse-cli-client`(wrapper of ClickHouse native command-line client) was added in 0.3.2-patch10, `clickhouse-tcp-client` will be available in 0.3.3 | -| Compatibility | Server < 20.7 | :x: | use 0.3.1-patch(or 0.2.6 if you're stuck with JDK 7) | -| | Server >= 20.7 | :white_check_mark: | use 0.3.2 or above. All [active releases](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) are supported. | -| Data Format | RowBinary | :white_check_mark: | `RowBinaryWithNamesAndTypes` for query and `RowBinary` for insertion | -| | TabSeparated | :white_check_mark: | Does not support as many data types as RowBinary | -| Data Type | AggregatedFunction | :x: | limited to `groupBitmap` | -| | Array(\*) | :white_check_mark: | | -| | Bool | :white_check_mark: | | -| | Date\* | :white_check_mark: | | -| | DateTime\* | :white_check_mark: | | -| | Decimal\* | :white_check_mark: | `SET output_format_decimal_trailing_zeros=1` in 21.9+ for consistency | -| | Enum\* | :white_check_mark: | can be treated as both string and integer | -| | Geo Types | :white_check_mark: | Point, Ring, Polygon, and MultiPolygon | -| | Int\*, UInt\* | :white_check_mark: | UInt64 is mapped to `long` | -| | IPv\* | :white_check_mark: | | -| | Map(\*) | :white_check_mark: | | -| | Nested(\*) | :white_check_mark: | | -| | Object('JSON') | :white_check_mark: | supported since 0.3.2-patch8 | -| | SimpleAggregateFunction | :white_check_mark: | | -| | \*String | :white_check_mark: | | -| | Tuple(\*) | :white_check_mark: | | -| | UUID | :white_check_mark: | | -| High Availability | Load Balancing | :white_check_mark: | supported since 0.3.2-patch10 | -| | Failover | :white_check_mark: | supported since 0.3.2-patch10 | -| Transaction | Transaction | :white_check_mark: | supported since 0.3.2-patch11, use ClickHouse 22.7+ for native implicit transaction support | -| | Savepoint | :x: | | -| | XAConnection | :x: | | - -## Examples +| Category | Feature | Supported | Remark | +| ----------------- | ----------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| API | [JDBC](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) | :white_check_mark: | | +| | [R2DBC](https://r2dbc.io/) | :x: | will be supported in 0.3.3 | +| | [GraphQL](https://graphql.org/) | :x: | | +| Protocol | [HTTP](https://clickhouse.com/docs/en/interfaces/http/) | :white_check_mark: | recommended, defaults to `java.net.HttpURLConnection` and can be changed to `java.net.http.HttpClient`(less stable) | +| | [gRPC](https://clickhouse.com/docs/en/interfaces/grpc/) | :white_check_mark: | still experimental, works with 22.3+, known to has [issue](https://github.com/ClickHouse/ClickHouse/issues/28671#issuecomment-1087049993) when using LZ4 compression | +| | [TCP/Native](https://clickhouse.com/docs/en/interfaces/tcp/) | :white_check_mark: | `clickhouse-cli-client`(wrapper of ClickHouse native command-line client) was added in 0.3.2-patch10, `clickhouse-tcp-client` will be available in 0.3.3 | +| | [Local/File](https://clickhouse.com/docs/en/operations/utilities/clickhouse-local/) | :x: | `clickhouse-cli-client` will be enhanced to support `clickhouse-local` | +| Compatibility | Server < 20.7 | :x: | use 0.3.1-patch(or 0.2.6 if you're stuck with JDK 7) | +| | Server >= 20.7 | :white_check_mark: | use 0.3.2 or above. All [active releases](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) are supported. | +| Compression | [gzip](https://www.gzip.org/) | :white_check_mark: | | +| | [lz4](https://lz4.github.io/lz4/) | :white_check_mark: | default | +| | [zstd](https://facebook.github.io/zstd/) | :x: | | +| Data Format | RowBinary | :white_check_mark: | `RowBinaryWithNamesAndTypes` for query and `RowBinary` for insertion | +| | TabSeparated | :white_check_mark: | Does not support as many data types as RowBinary | +| Data Type | AggregatedFunction | :x: | limited to `groupBitmap` | +| | Array(\*) | :white_check_mark: | | +| | Bool | :white_check_mark: | | +| | Date\* | :white_check_mark: | | +| | DateTime\* | :white_check_mark: | | +| | Decimal\* | :white_check_mark: | `SET output_format_decimal_trailing_zeros=1` in 21.9+ for consistency | +| | Enum\* | :white_check_mark: | can be treated as both string and integer | +| | Geo Types | :white_check_mark: | Point, Ring, Polygon, and MultiPolygon | +| | Int\*, UInt\* | :white_check_mark: | UInt64 is mapped to `long` | +| | IPv\* | :white_check_mark: | | +| | Map(\*) | :white_check_mark: | | +| | Nested(\*) | :white_check_mark: | | +| | Object('JSON') | :white_check_mark: | supported since 0.3.2-patch8 | +| | SimpleAggregateFunction | :white_check_mark: | | +| | \*String | :white_check_mark: | | +| | Tuple(\*) | :white_check_mark: | | +| | UUID | :white_check_mark: | | +| High Availability | Load Balancing | :white_check_mark: | supported since 0.3.2-patch10 | +| | Failover | :white_check_mark: | supported since 0.3.2-patch10 | +| Transaction | Transaction | :white_check_mark: | supported since 0.3.2-patch11, use ClickHouse 22.7+ for native implicit transaction support | +| | Savepoint | :x: | | +| | XAConnection | :x: | | + +## Usage + +The library can be downloaded from both [Github Releases](../../releases) and [Maven Central](https://repo1.maven.org/maven2/com/clickhouse/). Development snapshots are available on [Sonatype OSSRH](https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/). + +```xml + + + ossrh + Sonatype OSSRH + https://s01.oss.sonatype.org/content/repositories/snapshots/ + + +``` ### Java Client @@ -69,10 +85,11 @@ Note: in general, the new driver(v0.3.2) is a few times faster with less memory ``` ```java -// endpoint: protocol://host[:port][/database][?param1=value1¶m2=value2...][#tag1,tag2,...] +// endpoint: protocol://host[:port][/database][?param[=value][¶m[=value]][#tag[,tag]] ClickHouseNode endpoint = ClickHouseNode.of("https://localhost"); // http://localhost:8443?ssl=true&sslmode=NONE -// endpoints: [defaultProtocol://]endpoint1[,endpoint2,endpoint3,...][/defaultDatabase][?defaultParameters][#efaultTags] -ClickHouseNodes endpoints = ClickHouseNodes.of("http://(https://explorer@play.clickhouse.com:443),localhost,(tcp://localhost?!auto_discovery#experimental),(grpc://localhost#experimental)?failover=3#test") +// endpoints: [defaultProtocol://]endpoint[,endpoint][/defaultDatabase][?defaultParameters][#defaultTags] +ClickHouseNodes endpoints = ClickHouseNodes.of("http://(https://explorer@play.clickhouse.com:443),localhost," + + "(tcp://localhost?!auto_discovery#experimental),(grpc://localhost#experimental)?failover=3#test") try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP); ClickHouseResponse response = client.connect(endpoint) // or client.connect(endpoints) @@ -113,7 +130,7 @@ try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.H ``` ```java -// jdbc:(ch|clickhouse):[defaultProtocol://]endpoint1[,endpoint2,endpoint3,...][/defaultDatabase][?defaultParameters][#efaultTags] +// jdbc:(ch|clickhouse):[defaultProtocol://]endpoint[,endpoint][/defaultDatabase][?defaultParameters][#defaultTags] String url = "jdbc:ch:https://play.clickhouse.com:443"; Properties properties = new Properties(); properties.setProperty("user", "explorer"); @@ -130,6 +147,8 @@ try (Connection conn = dataSource.getConnection(); } ``` +More examples can be found at [here](../../tree/master/examples/jdbc). + ## Build with Maven Use `mvn -DskipITs clean verify` to compile and generate packages if you're using JDK 8. To create a multi-release jar (see [JEP-238](https://openjdk.java.net/jeps/238)), please use JDK 11+ with `~/.m2/toolchains.xml` like below, and run `mvn -Drelease -DskipITs clean verify` instead. @@ -193,4 +212,4 @@ java -DdbHost=localhost -jar target/benchmarks.jar -t 1 \ -p statement=prepared Query.selectInt8 ``` -It's time consuming to run all benchmarks against all drivers using different parameters for comparison. If you just need some numbers to understand performance, please refer to table below and some more details like CPU and memory usage mentioned at [here](https://github.com/ClickHouse/clickhouse-jdbc/issues/768)(still have plenty of room to improve according to ranking at [here](https://github.com/go-faster/ch-bench)). +It's time consuming to run all benchmarks against all drivers using different parameters for comparison. If you just need some numbers to understand performance, please refer to [this](https://github.com/ClickHouse/clickhouse-jdbc/issues/768)(still have plenty of room to improve according to ranking at [here](https://github.com/go-faster/ch-bench)). diff --git a/examples/grpc/pom.xml b/examples/grpc/pom.xml index 7dcae357f..a1c7ee564 100644 --- a/examples/grpc/pom.xml +++ b/examples/grpc/pom.xml @@ -51,12 +51,20 @@ https://github.com/ClickHouse/clickhouse-jdbc/actions + + + ossrh + Sonatype OSSRH + https://s01.oss.sonatype.org/content/repositories/snapshots/ + + + 2022 UTF-8 UTF-8 - 0.3.2-patch9 + 0.3.3-SNAPSHOT 3.8.1 diff --git a/examples/jdbc/pom.xml b/examples/jdbc/pom.xml index 5db22317f..0c273acd2 100644 --- a/examples/jdbc/pom.xml +++ b/examples/jdbc/pom.xml @@ -51,6 +51,14 @@ https://github.com/ClickHouse/clickhouse-jdbc/actions + + + ossrh + Sonatype OSSRH + https://s01.oss.sonatype.org/content/repositories/snapshots/ + + + 2022 UTF-8 From c1ba7106ba8406129fe2a07966713e3f5c33987a Mon Sep 17 00:00:00 2001 From: Zhichun Wu Date: Tue, 30 Aug 2022 21:54:26 +0800 Subject: [PATCH 2/2] Update workflows --- .github/workflows/build.yml | 2 ++ .github/workflows/third_party_libs.yml | 2 +- .github/workflows/timezone.yml | 2 ++ 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f3ad7fc05..cb7f99fc4 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -9,6 +9,7 @@ on: paths-ignore: - "**.md" - "docs/**" + - "examples/**" - "**/CHANGELOG" pull_request: @@ -19,6 +20,7 @@ on: paths-ignore: - "**.md" - "docs/**" + - "examples/**" - "**/CHANGELOG" workflow_dispatch: diff --git a/.github/workflows/third_party_libs.yml b/.github/workflows/third_party_libs.yml index b4c0c7bb1..49406dcff 100644 --- a/.github/workflows/third_party_libs.yml +++ b/.github/workflows/third_party_libs.yml @@ -6,7 +6,7 @@ on: version: description: "Release version" required: true - default: "1.2.0" + default: "1.3.0" jobs: release: diff --git a/.github/workflows/timezone.yml b/.github/workflows/timezone.yml index 55cec0f2a..afc580576 100644 --- a/.github/workflows/timezone.yml +++ b/.github/workflows/timezone.yml @@ -8,6 +8,7 @@ on: paths-ignore: - "**.md" - "docs/**" + - "examples/**" - "**/CHANGELOG" pull_request: @@ -18,6 +19,7 @@ on: paths-ignore: - "**.md" - "docs/**" + - "examples/**" - "**/CHANGELOG" workflow_dispatch: