Release notes from clickhouse-java

Release v0.7.2

2024-12-31T06:11:04Z

New Components

jdbc-v2 - pre-release version of upcoming clickhouse-jdbc replacement. Supports basic functionality, works only with client-v2.
More information will be available after its release

Highlights

[repo] Added shaded packages with requires a set of dependencies. Use all classified for client-v2 full package.
Use shaded-all for old jdbc driver.
[client-v2] New Data Writer API was added. It allows to gain a control over writing data to low-level output stream.
This API makes it possible to write compressed data directly to server. See com.clickhouse.client.api.Client#insert(java.lang.String, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings)
(#2034)

New Features

[client-v2] Added ability to specify client name. It means User-Agent will be filled with proper information (#1948)
[client-v2] Implemented statement parameters for queryAll and queryRecords API methods. (#1979)
[client-v2] Implemented string to number conversion. (#2014)
[client-v1] Added basic auth support for proxies. Now you can specify username/password when connecting via a proxy that requires it with HttpURLConnection and Apache HttpClient.
[client-v2] Enum columns can be read as string and number. Previously only as number. Now number matching string constant is returned when get as string. (#2028)
[client-v2] Client will load some server context (timezone, user) right after build. (#2029)

Bug Fixes

[jdbc] Fixed default value for result_overflow_mode setting. (#1932)
[client-v2] Fixed reading float/double values. Previously was prevented by incorrect overflow check. (#1954)
[client-v2] Fixed issue with enabling client compression. Previously flag was ignore in some cases. (#1958)
[client-v2] Fixed issue with reading Array(UInt64) because of incorrect class used to create internal array. (#1990)
[client-v2] Fixed ClickHouseLZ4OutputStream issue of sending empty frame when no data left in uncompressed buffer. (#1993)
[client-v2] Fix handling ConnectTimeoutException in retry and wrapping logic. (#2015)

Release v0.7.1-patch1

2024-11-07T17:56:04Z

Bug Fixes

[JDBC] Fixed java.lang.NoClassDefFoundError: com/clickhouse/client/internal/apache/hc/core5/http2/HttpVersionPolicy (#1912)
[client-v2] Fixed multiple issues with error message handling. (#1906)
[client-v2] Fixed primitive types conversion. Now client correctly handles numbers to boolean and vice-versa. (#1908)

Release v0.7.1

2024-11-04T03:45:18Z

New Features

[client-v2] Implemented more friendly number conversion. Now it is possible to convert smaller type to bigger one.
It is also possible to convert bigger into smaller if value fits into the range. (#1852)
[client-v2] Ported a feature that allows to remember DB roles for a client instance. See com.clickhouse.client.api.Client#setDBRoles
for details. (#1832)
[client-v2] Ported a feature that allows adding comments to a query.
See com.clickhouse.client.api.insert.InsertSettings#logComment and com.clickhouse.client.api.query.QuerySettings#logComment
for details. (#1836)
[client-v2] Added support for SSL Authentication with client certificates. (#1837)
[client-v2] Implemented a way to define a custom matching between a column name and a field in a POJO in Client#register method. (#1866)
[client-v1, client-v2] Implemented HTTP Basic authentication and made it a default auth method for HTTP interface. It
was done to address problem with passwords contianing special and UTF8 characters. New configuration option
com.clickhouse.client.http.config.ClickHouseHttpOption.USE_BASIC_AUTHENTICATION for client v1 is added. For client v2
use com.clickhouse.client.api.Client.Builder#useHTTPBasicAuth method. (#1305)

Dependency Updates

[client] Bumped org.apache.avro:avro version to 1.11.4 (#1855)

Documentation

[client] Added links to javadoc for all classes in the README.md (#1878)

Bug Fixes

[client-v2] Fixed deserializing nullable columns of Nested type (#1858)
[client-v2] Fixed dependencies needed for compression to work out of the box (#1805)
[client-v2] Fixed dependency on SNAPSHOT component (#1853)
[client-v2] Fixed using scale from a column definition when deserializing DateTime64 values (#1851)
[client-v2] Fixed applying database from insert settings (#1868)
[client-v2] Fixed error handling from server (#1874)
[client-v2] Fixed SerDe for SimpleAggregateFunction columns (#1876)
[client] Fixed handling error from server in response with 200 OK status. Happens when
send_progress_in_http_headers is requested and query runs for a long time. (#1821)
[jdbc] Fixed incorrect error logging (#1827)
[client-v2] Fixed handling tuples in arrays (#1882)
[client-v2] Fixed passing insert_duplication_token through InsertSettings. (#1877)

Release v0.7.0

2024-10-02T06:38:48Z

Deprecations

Following deprecated components are removed:
- clickhouse-cli-client
- clickhouse-grpc-client

Important Changes

[client-v2] New transport layer implementation is used by default. It is still possible to switch back
using old implementation by setting com.clickhouse.client.api.Client.Builder#useNewImplementation to false. (#1847)

New Features

[client-v2] Now there is an easy way to set custom HTTP headers globally for client and per operation.
See com.clickhouse.client.api.Client.Builder.httpHeader(java.lang.String, java.lang.String) for details. (#1782)
[client-v2] Now there is a way to set any server settings globally for client and per operation.
See com.clickhouse.client.api.Client.Builder.serverSetting(java.lang.String, java.lang.String) for details. (#1782)
[client-v2] Added support for writing AggregateFunction values (bitmap serialization). !! Reading is not
supported but will be added in the next release. (#1814)
[r2dbc] Defer connection creation. This allows pool to create a new instance on every subscription,
instead of always returning the same one. (#1810)

Performance Improvements

[client-v2] Improved reading fixed length data like numbers. It is possible to configure readers to
use pre-allocated buffers to avoid memory allocation for each data row/block. Significantly reduces GC pressure.
See com.clickhouse.client.api.Client.Builder.allowBinaryReaderToReuseBuffers for details. (#1816)
[client-v2] New API method introduced to read data directly to a POJO. Deserializers for POJO classes are compiled into
bytecode (with help of https://asm.ow2.io/ library) and optimized for each schema. It is great performance boost
because data is read without copying it into temporary structures. Code can be optimized by JVM while runtime as SerDe
code is implemented without reflection using JVM bytecode. Using bytecode makes handling primitive types without values boxing. (#1794,
#1826)
[client-v2] Optimized reading columns - internally data is read into map of column-values. It is done
to allow reading same column more than once. Previously map was cleared each row what caused a lot
internal objects creation. Now values are overridden because schema doesn't change between rows. (#1795)

Documentation

[client-v2] Added example for Kotlin (#1793)
[doc] Main documentation on official ClickHouse website is updated. Each client has its own page with detailed information now.
Added documentation for the Client V2. See https://clickhouse.com/docs/en/integrations/java.

Bug Fixes

[client-v2] Fix for cases when missing operation metrics were causing NPE. (#1846)
[client-v2] Fix for handling empty result by BinaryFormat readers. (#1845)
[jdbc] Content of an artifact 'clickhouse-jdbc-{version}-all.jar' is fixed and contains all required classes from clickhouse-client
and clickhouse-data. (#1842)
[client-v1, jdbc] Endpoints definition parsing fixed to grub properties correctly. Now even properties with key-value
pairs are supported. (#1841, #1665)

Release v0.6.5

2024-09-01T14:31:13Z

Deprecations

Following components will be deprecated and removed in 0.7.0 release:
- clickhouse-cli-client
- clickhouse-grpc-client
Projects cli-client and grpc-client are excluded from release and build.
No more builds for non-lts Java versions - no more Java 9 release builds.

Performance Improvements

[client-v2] queryAll() optimized to use less memory (#1779)
[client-v2] Client.Builder#setClientNetworkBufferSize introduced to allow increasing a buffer that is used
to transfer data from socket buffer to application memory. When set to >= of send/receive socket buffer size it
significantly reduces number of system calls and improves performance. (#1784)

New Features

[client-v2] Client will retry on NoHttpResponseException when using Apache HTTP client.
It is useful when close/stale connection is leased from connection pool. No client will
retry one more time instead of failing. Client.Builder#retryOnFailures and Client.Builder#setMaxRetries were
introduced to configure client behavior. (#1768)

Bug Fixes

[client-v2] Correct timezone used when reading DateTime values. Affects how date/datetime values
are read when session_timezone is used (#1780)
[client-v2] Fix reading big integers. Previously was causing incorrect values
(#1786)
(#1776)
[client-v2] Fix server compressions when using a client instance concurrently
(#1791)
[client-v2] Fix reading arrays as list. Also affected reading nested arrays (#1800)
[client-v1] Fix handling summary metadata for write operations. Previously was causing empty metadata

Release v0.6.4

2024-08-17T04:26:56Z

Deprecations

Following components will be deprecated and archived in next release:
- clickhouse-cli-client
- clickhouse-grpc-client
No more builds for non-lts Java versions - no more Java 9 release builds.
Lowest supported Java version will be 11.
- Java 11 support will be ended before the end of 2023.
- It is recommended to use Java 21.

Important Changes

[Client-V1] Fix for handling DateTime without timezone when session_timezone is set. Now server timezone
is parsed from server response when present (#1464)

New Features

[Client-V1/Apache HTTP] More configuration parameters for connection management. Useful for tuning performance.
(#1771)
- com.clickhouse.client.config.ClickHouseClientOption#CONNECTION_TTL - to configure connection time-to-live
- com.clickhouse.client.http.config.ClickHouseHttpOption#KEEP_ALIVE_TIMEOUT - to configure keep-alive timeout
- com.clickhouse.client.http.config.ClickHouseHttpOption#CONNECTION_REUSE_STRATEGY - defines how connection pool behaves.
  If FIFO is selected then connections are reused in the order they were created. It results in even distribution of connections.
  If LIFO is selected then connections are reused as soon they are returned to the pool.
  Note: only for APACHE_HTTP_CLIENT connection provider.
- Additionally switched to using LAX connection pool for Apache Connection Manager to improve performance
  for concurrent requests.
[Client-V2] Connection pool configuration #1766
- com.clickhouse.client.api.Client.Builder.setConnectionRequestTimeout - to configure connection request timeout.
  Important when there are no connections available in the pool to fail fast.
- com.clickhouse.client.api.Client.Builder.setMaxConnections - configures how soft limit of connections per host.
  Note: Total number of connections is unlimited because in most cases there is one host.
- com.clickhouse.client.api.Client.Builder.setConnectionTTL - to limit connection live ignoring keep-alive from server.
- com.clickhouse.client.api.Client.Builder.setConnectionReuseStrategy - to configure how connections are used.
  Select FIFO to reuse connections evenly or LIFO (default) to reuse the most recently active connections.
[Client-V2] All operations are now executed in calling thread to avoid extra threads creation.
Async operations can be enabled by com.clickhouse.client.api.Client.Builder.useAsyncRequests (#1767)
[Client-V2] Content and HTTP native compression is supported now Currently only LZ4 is available. (#1761)
[Client-V2] HTTPS support added. Required to communicate with ClickHouse Cloud Services.
Client certificates are supported, too. (#1753)
[Client-V2] Added support for HTTP proxy (#1748)

Documentation

[Client-V2] Spring Demo Service as usage example (#1765)
[Client-V2] Examples for using text based formats (#1752)

Bug Fixes

[Client-V2] Data is read fully from a stream. Important for Cloud instances (#1759)
[Client-V2] Timezone from a server response is now used to parse DateTime values (#1763)
[Client-V1] Timezone from a server response is now used to parse DateTime values (#1464)

Release v0.6.3

2024-07-20T16:56:44Z

Important Changes

[Client-V1] Changed how User-Agent string is generated. Now ClickHouse-JavaClient portion is appended in all cases.
It is still possible to set custom product name that will be the first part in User-Agent value.
(#1698)

New Features

[Client-V1/Apache HTTP] Retry on NoHttpResponseException in Apache HTTP client.
Should be used with causes because it is not always possible to resend request body.
Behaviour is controlled by com.clickhouse.client.http.config.ClickHouseHttpOption#AHC_RETRY_ON_FAILURE.
Works only for Apache HTTP client because based on its specific behavior(#1721)
[Client-V1/Apache HTTP] Connection validation before sending request.
Behaviour is controlled by com.clickhouse.client.http.config.ClickHouseHttpOption#AHC_VALIDATE_AFTER_INACTIVITY.
By default, connection is validated after being in the pool for 5 seconds. (#1722)

Bug Fixes

[Client-V2] Fix making it possible to pass URL starting with "https://" for secure endpoints (#1718)
[Client-V2] Fix minimizes number of threads used by the client. It reduces resource usage significantly. (#1691)
[Client-V1] Fix slowness ( > 1 min) caused by incorrect localhost IP determination while initialization of the client (#1729)
[Client-V2] Make client instance closeable to free underlying resource (#1733)

Release v0.6.2

2024-06-29T19:06:01Z

New Features

Describe non-executed SELECT queries in prepared statements to provide metadata (#1430)
Command execution in the client API (#1693)
Added com.clickhouse.client.ClickHouseResponseSummary#getQueryId() (#1636)
Added support for SSL for the Client V2
Added proxy support for Client V2 (#1694)
Added more examples for

Release v0.6.1

2024-06-11T12:42:49Z

New Features

Alpha version of the new client API. See example https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2.

Bug Fixes

Fix proper handling of ClickHouseResult to release DB connection (#1538
Not it is possible to get raw input stream from a server response to read data in any format by user.
- #1494
- #1567
- #1475
- #1376
Exception context remove from a message. Server information not present anymore but available thru com.clickhouse.client.ClickHouseException#getServer (#1677)

Release v0.6.0-patch5

2024-05-28T18:44:15Z

Bug Fixes

Roles (memorized by client) can be reset with 'SET ROLE NONE' query (#1647)
MaxBufferSize can be greater than internal MAX value now
Updated example project to use the latest version of the client