pan3793 / clickhouse-java

Java client and JDBC driver for ClickHouse

ClickHouse Java Libraries

Java libraries for connecting to ClickHouse and processing data in various formats. Java client is async, lightweight, and low-overhead library for ClickHouse; while JDBC and R2DBC drivers are built on top of the Java client with more dependencies and features. Java 8 or higher is required to use the libraries. In addition, please use ClickHouse 20.7+ or any of active releases.

Features

Category	Feature	Supported	Remark
API	JDBC	✅
	R2DBC	✅	supported since 0.4.0
Protocol	HTTP	✅	recommended, defaults to java.net.HttpURLConnection and it can be changed to java.net.http.HttpClient(unstable) or Apache HTTP Client 5. Note that the latter was added in 0.4.0 to support custom socket options.
	gRPC	✅	⚠️ experimental, works with 22.3+, known to has issue with lz4 compression and may cause high memory usage on server
	TCP/Native	✅	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.5
	Local/File	❌	clickhouse-cli-client will be enhanced to support clickhouse-local
Compatibility	Server < 20.7	❌	use 0.3.1-patch(or 0.2.6 if you're stuck with JDK 7)
	Server >= 20.7	✅	use 0.3.2 or above. All active releases are supported.
Compression	lz4	✅	default
	zstd	✅	supported since 0.4.0, works with ClickHouse 22.10+
Data Format	RowBinary	✅	RowBinaryWithNamesAndTypes for query and RowBinary for insertion
	TabSeparated	✅	⚠️ does not support as many data types as RowBinary
Data Type	AggregateFunction	❌	⚠️ limited to groupBitmap; 64bit bitmap was NOT working properly before 0.4.1
	Array(*)	✅
	Bool	✅
	Date*	✅
	DateTime*	✅
	Decimal*	✅	SET output_format_decimal_trailing_zeros=1 in 21.9+ for consistency
	Enum*	✅	can be treated as both string and integer
	Geo Types	✅	Point, Ring, Polygon, and MultiPolygon
	Int*, UInt*	✅	UInt64 is mapped to long
	IPv*	✅
	Map(*)	✅
	Nested(*)	✅	⚠️ broken before 0.4.1
	Object('JSON')	✅	supported since 0.3.2-patch8
	SimpleAggregateFunction	✅
	*String	✅	⚠️ requires use_binary_string=true for binary string support since v0.4.0
	Tuple(*)	✅
	UUID	✅
High Availability	Load Balancing	✅	supported since 0.3.2-patch10
	Failover	✅	supported since 0.3.2-patch10
Transaction	Transaction	✅	supported since 0.3.2-patch11, use ClickHouse 22.7+ for native implicit transaction support
	Savepoint	❌
	XAConnection	❌
Misc.	Implicit Type Conversion	✅	String/number to Date/Time/Timestamp and more
	Centralized Configuration	✅	supported since 0.4.2, custom server setting custom_jdbc_config for all connected JDBC clients

Usage

The library can be downloaded from both Github Releases and Maven Central. Development snapshots(aka. nightly build) are available on Sonatype OSSRH.

<repositories>
    <repository>
        <id>ossrh</id>
        <name>Sonatype OSSRH</name>
        <url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
    </repository>
</repositories>

Java Client

See the client docs on the ClickHouse website.

JDBC Driver

See the jdbc driver docs on the ClickHouse website.

Contributing

Check out our contributing guide.