Release notes from clickhouse-java

Release v0.9.8

2026-03-19T00:54:28Z

Improvements

[client-v2] Added Records#getSchema() to expose table schema metadata even when query result is empty. (#2777)

Bug Fixes

[jdbc-v1, jdbc-v2] Fixed type mapping/conversion behavior for large unsigned integer values (issue #2779), including related test coverage updates. (#2779)
[jdbc-v2] Fixed off-by-one bug in ArrayResultSet#next() that could return true one extra time and then fail with SQLException: No current row. (#2790)
[jdbc-v2] Fixed handling of malformed SELECT-like queries (for example, SELECT a, FROM table): previously, the driver could fail to read returned data when query type was not inferred before execution; now it detects a returned result set at runtime from the server response and reads it correctly. (#2784)

Updated Dependencies

[repo] Upgraded at.yawk.lz4:lz4-java from 1.10.2 to 1.10.4 to pick up native performance fixes. (#2778)
[repo] Upgraded com.fasterxml.jackson.core:jackson-core from 2.17.2 to 2.18.6 in jdbc-v2. (#2767)
[repo] Upgraded com.fasterxml.jackson.core:jackson-core from 2.17.2 to 2.18.6 in examples/client-v2. (#2766)

Release v0.9.7

2026-03-20T22:29:08Z

Important Notes

Behavior of Client.Builder.addEndpoint(String) was changed: now it saves URL base path (more in #2344). Previously this method was ignoring base path. Please pay attention that this method still ignores query parameters. Endpoint is NOT like JDBC URL. Client has designated builder method to set configuration.

Breaking Changes

[client-v2] Client.Builder#build() now throws ClientMisconfigurationException when an unknown configuration property is passed. Previously, unknown properties were silently ignored what caused unexpected behaviour and problems. To restore the old behavior, add ignore_unknown_config_key=true to the client properties. JDBC driver-only properties (e.g. ssl) are no longer forwarded to the underlying client. (#2658)
[client-v2] Date/Date32 columns are now decoded as LocalDate without any timezone adjustment. Previously, Date values could be returned as ZonedDateTime. Applications that need a ZonedDateTime must construct it from the returned LocalDate using their own timezone context. More read about it - https://clickhouse.com/docs/integrations/language-clients/java/jdbc_date_time_guide (#2727)

Improvements

[client-v2] Added option to send query parameters in the HTTP request body using multipart form encoding. Enabled via the new client.http.use_form_request_for_query configuration property (or Client.Builder#useHttpFormDataForQuery()). Useful when query parameters would exceed URL length limits. (#2324)
[client-v2] QueryResponse, InsertResponse, and CommandResponse now expose getServerDisplayName() to retrieve the value of the X-ClickHouse-Server-Display-Name HTTP response header. A full map of whitelisted response headers is accessible via getResponseHeaders(). (#2347)
[client-v2] Added getObjectArray() to ClickHouseBinaryFormatReader and GenericRecord to read Array(...) columns as Object[], including recursive support for nested arrays. getStringArray() now also handles Array(Enum*) by returning enum names. (#2738)
[jdbc-v2] Added support for reading and writing byte[] for String/FixedString columns. PreparedStatement#setBytes() encodes the value as a ClickHouse unhex() expression to preserve raw bytes; ResultSet#getBytes() returns the UTF-8 bytes of the string value. (#2734)
[client-v2] Preserve path part from URL passed to builder method `addEndpoint() (#2691)

Date and Time Handling

[docs] Added a document that explains how driver handles different date/time values.
[client-v2, jdbc-v2] Fixed writing Date/Time/Timestamp values so that timezone conversions are performed explicitly. Previously, timezone-naïve encoding caused day-shift and precision bugs, especially when a Calendar or non-default JVM timezone was in use. (#2701, #2065, #2496, #1220, #1117, #1048, #2381, #1735, #2542, #2557)
[client-v2, jdbc-v2] Fixed reading Date/Time/DateTime values to be consistent and correct. Date/Date32 are now decoded as LocalDate (no timezone), while Time/Time64 are decoded as UTC-based LocalDateTime. New getLocalTime() API added to readers for LocalTime access. Reading date/time from Dynamic and Variant columns is also fixed. (#2727)
[jdbc-v2] DatabaseMetaDataImpl#getTypeInfo() now returns type information in deterministic alphabetical order, matching v1 driver behavior. (#2733)

SQL Parser (jdbc-v2)

[jdbc-v2] Fixed SQL parser failing to handle ClickHouse keywords used as table names or column aliases (e.g. AS value, FROM date). Both the ANTLR4 and JavaCC parsers now maintain a list of non-reserved keywords allowed in identifier positions. Also fixed parsing of DESCRIBE (SELECT ...), IN operator in SELECT, and bracketed array access in expressions. (#2718)
[jdbc-v2] Updated SQL parsers to recognise new ClickHouse keywords (ABI, ARGUMENTS, DRY, LANGUAGE, RETURNS, RUN) introduced in recent ClickHouse HEAD builds. Previously, queries using these keywords as identifiers would fail to parse. (#2761)
[jdbc-v2] Fixed SQL parser failing on statements containing the ^ (caret) operator, such as toJSONString(data.^header_index). A new CARET token is now recognised and allowed in dotted identifier chains. (#2768)

Array and Collection Handling

[jdbc-v2] Fixed DataTypeConverter causing NPE when converting nested arrays to strings (e.g. ResultSet#getString() on an Array(Array(...)) column). The converter is now re-entrancy-safe. Previously was throwing NullPointerException. (#2723)
[client-v2, jdbc-v2] Fixed conversion of multi-dimensional List/array values into Java arrays. Child array dimensions are now calculated correctly from the parent depth level. Previously, converting List<List<T>> or similar structures produced incorrect results. (#2741)
[client-v2] Fixed binary array decoding when the first element of an array is an empty Map or List. Previously, this caused a type mismatch error during array population. (#2499, #2657, #2703)

Bug Fixes

[jdbc-v2] Fixed DatabaseMetaDataImpl#getJDBCMajorVersion() and getJDBCMinorVersion() returning the ClickHouse driver version instead of the supported JDBC specification version. Now correctly returns 4 and 2 (JDBC 4.2). (#2736)
[jdbc-v2] Added mapping for all known ClickHouse table engines to JDBC table types. Added MATERIALIZED VIEW as a new table type. getTables() now correctly reports remote/external engine tables that were previously invisible. (#2664)
[jdbc-v2] Fixed NullPointerException in JDBC type metadata for columns of type Map, IPv4, IPv6, UUID, BFloat16, Decimal256, Geometry, all Interval* types, JSON, LowCardinality, Nullable, Variant, Dynamic, and others. Previously these types had no Java class mapping. (#2711)
[jdbc-v2] ClickHouse server error codes are now propagated to SQLException#getErrorCode(). Previously, SQLException was created without the vendor error code, making it impossible to distinguish error types programmatically. (#2717)
[client-v2] Fixed max_execution_time not being sent correctly to the server. Previously, it was treated as a client option and ignored by ClickHouse; it is now transmitted as a server setting. (#2750)
[client-v2] Fixed hasValue(columnName) throwing an exception when the column name does not exist. Previously, referencing an unknown column or an out-of-range index via hasValue() would throw; it now returns false. (#2755)
[jdbc-v2] Fixed PreparedStatement reporting missing parameters using 0-based indices in the error message. JDBC parameter positions are 1-based; the error message now reflects this correctly. (#2749)
[jdbc-v2] Ported legacy JDBC v1 connection properties (CUSTOM_HTTP_PARAMS, CUSTOM_SETTINGS, HTTP_CONNECTION_PROVIDER, REMEMBER_LAST_SET_ROLES, USE_SERVER_TIME_ZONE_FOR_DATES) to JDBC v2. Required for integrations that share JDBC v1/v2 configuration code. custom_http_params and custom_settings values are converted to server settings automatically. (#2757)
[client-v2, jdbc-v2] Fixed custom_-prefixed configuration properties not being forwarded to the server as custom settings when using the custom_ prefix. Also fixed driver-only properties (e.g. ssl) being incorrectly forwarded to the HTTP client. (#2658)

Release v0.9.6

2026-01-12T20:06:13Z

Release is aimed to address potential security risk in one of the dependencies (see below). We strongly recommend to upgrade.

Dependencies

[repo] - upgraded lz4-java to 1.10.2. Previously used version had a vulnerability https://www.cve.org/CVERecord?id=CVE-2025-66566. (#2706)
[repo] - upgraded commons-lang3 to 3.20.0. Previously used version had a vulnerability https://www.cve.org/CVERecord?id=CVE-2025-48924. (#2696)

New Features

[jdbc-v2] - support of dot notation for table names without quotes. (#2650)

Release v0.9.5

2025-12-19T04:13:37Z

New Features

[client-v2] Log durations in ISO-8601 duration format (#2660)
[jdbc-v2] Added support for getResultSet() method in Array data types. (#1545, #2683)
[jdbc-v2] Added handling for Time and Time64 data types in JDBC. (#2682)

Bug Fixes

[client-v2] Fixed reading columns of Array with component type Variant. For example, Array(Variant(String, Int32)). (#2602)
[jdbc-v2] Fixed backward compatibility for getPrimaryKeys() method. (#2654)
[jdbc-v2] Fixed array conversion issues with multidimensional arrays and nested arrays. (#2457)
[jdbc-v2] Fixed backward compatibility issues with older ClickHouse versions by replacing :: cast operator with CAST function in prepared statements. Fixed issue with reading database version on older versions. (#2654, #2227)
[jdbc-v2] Reviewed and fixed database metadata support flags and return values. (#2520, #778, #2519)
[jdbc-v2] Added verification tests for issues #1999, #1015, #2155 (#2659)

Release v0.9.4

2025-11-07T00:18:02Z

New Features

[client-v2] Added support for different compression algorithms when HTTP compression is enabled. (#2645)

Bug Fixes

[client-v1] Fixes issue linked to a enabled by default HTTP compression in ClickHouse 25.10. (#2636)

Release v0.9.3

2025-10-31T22:52:20Z

Important Changes

[jdbc-v2] SQL parser from v1 is ported to v2 to address multiple issues with SQL parsing. The ANTLR4-based parser is
still an option and will be developed further. The main difference between parses is completeness of their grammar:
JavaCC grabs only needed information and skips parsing of the rest (what makes it work for most cases) while ANTLR4
has more complete grammar and can detect type of some complex statements more accurate than JavaCC.
To use it set com.clickhouse.jdbc.DriverProperties#SQL_PARSER to ANTLR4.
(#2579). This fixes issue:
- #2574
- #2568
- #2537
- #2595
- #2617
- #2569
- #2570
- #2571
- #2572
- #2573
- #2609
- #2527
[repo] New artifact clickhouse-jdbc-all added to address issue when maven package qualifiers may not be used.
This artifact should is a copy of clickhouse-jdbc:all but should be used only when required. (#2625)

Improvements

[client-v2] Added getShortArray() and getStringArray() to ClickHouseBinaryFormatReader. (#2604)
[client-v2] Added result_rows and elapsed_time to summary object. (https://github.com/ClickHouse/clickhouse-java/pull/1633/files)

Bug Fixes

[jdbc-v2] Fixed issue with maxRows in Statement when additional settings were used to limit result set size.
It caused problems with read-only users because such users may not change settings in most cases. Now when maxRows is
set then ResultSet will skip extra rows. (#2582)
[jdbc-v2] Fixed issue with driver version. Previously version of a library was converted to minor and major version.
But this approach doesn't work well with 0.9.x versions. Now major and minor versions are combined by shifting major.
Patch version becomes a minor version. (#2410)
[jdbc-v2, client-v2] Fixed converting different data types to a string. For example, there was an issue with IP
address when toString() was used and returned \0.0.0.0 instead of 0.0.0.0. (#2575)
[jdbc-v2] Fixed issues around spatial data (GEO types). (#2577)
[client-v2] Fixed issue with current user name. If user name is set then it will be used event after reading
server context. (#2247)
[client-v2] Fixed issue with network timeout settings when default value failed to be cast to Long. (#2597)
[jdbc-v2] Fixed getting metadata for nullable columns. (#2586)
[jdbc-v2, client-v2] Fixed issues related to reading JSON data type. Fixed reading JSON columns with arrays. Previously was causing exceptions like
com.clickhouse.client.api.ClientException: Unsupported data type with tag 101 at ...
(#2598, #2593,
#2613, #2102)
[client-v2] Fixed configuration parameter type for socket_linger to match documentation. (#2524)
[client-v2] Fixed handling exceptions in http client code. Now response object is always closed to prevent connection leaking. (#2615)
[jdbc-v2, client-v2] Fixed issue with duplicate column names in a result set. (#2459, #2336)
[jdbc-v2] Fixed ANTLR4 parse issue with filter clause along with aggregate function. (#2631)

Release v0.9.2

2025-09-05T18:39:46Z

Important

There is a new artifact clickhouse-jdbc-0.9.2-all-dependencies.jar. This include all dependencies shaded even public APIs like slf4j. It may be a problem when integration with application needed thru such interfaces.

Improvements

[jdbc-v2] Classes com.clickhouse.jdbc.ClientInfoProperties and com.clickhouse.jdbc.DriverProperties moved to public
API. (#2521)
[jdbc-v2] Implemented isBeforeFirst, isAfterLast, isFirst, isLast methods for ResultSet and ResultSetMetaData.
Improved test coverage for ResultSetImpl. (#2530)
[jdbc-v2] Implemented createArray and createStruct methods for Connection interface. Method createStruct
should be used to create Tuple values and createArray to create various arrays. (#2523)
[jdbc-v2] Implemented setNetworkTimeout of Connection interface. Used to fail fast when network operation fails. Related to
stale connection problem. (#2522)
[client-v2] Added support for JSON with predefined paths. Previously columns with definition like JSON(a string, b.c Int32)
were not supported. (#2531)

Bug Fixes

[jdbc-v2] Fixed issue creating array of tuples with createArray method of Connection interface.
(#2360)
[jdbc-v2] Fixed issue with reading nested arrays. (#2539)
[jdbc-v2] Fixed issue with not shaded antlr4-runtime dependency. Potential problem for Apache Spark users. (#2553)
[jdbc-v2] Fixed issue with parsing CTE for prepared statement. (#2551)
[jdbc-v2] Fixed issue with parsing SQL containing view parameters. (#2547)
[jdbc-v2] Fixed issue with InsertSettings when two concurrent insert operations sharing same settings object may be insert
wrong columns or to a wrong table. (#2550)
[jdbc-v2] Fixed issue with batch insert when it is not cleared after execution. Now batch is cleared after execution even on failure. (#2548)
[jdbc-v2] Fixed DatabaseMetadataImpl to return result set with defined by spec structure. Resolves issue for many database tools
relying on metadata. (#2396)
[jdbc-v2] Fixed DatabaseMetadataImpl to return empty result set where appropriate. (#2517)
[jdbc-v2] Fixed issue with verbose logging. (#2148)
[client-v2] Fixed issue with reading JSON with predefined paths. (#2462)

Release v0.9.1

2025-07-30T19:24:48Z

New Features

[client-v2] Added option to set SNI for SSL connections. See com.clickhouse.client.api.Client.Builder.sslSocketSNI (#2467)
[client-v2, jdbc-v2] Added support for Time and Time64 data types. (#2487)
[client-v2] Added utility methods to format Instant to a DB DateTime format. See com.clickhouse.client.api.DataTypeUtils.formatInstant(java.time.Instant, com.clickhouse.data.ClickHouseDataType) (#2501, #2456)

Improvements

[client-v2] Improved exceptions and error handling. The com.clickhouse.client.api.ClickHouseException became a root for
ServerException and ClientException. com.clickhouse.client.api.ClickHouseException.isRetryable is added to determine if
exception caused in a retriable state. It means that catching such exception application may repeat operation to fix a
problem. (#2453)
[client-v2] Improved configuration handling. (#2470)
[client-v2] Custom type hint for the client to make Reader and GenericRecord return specific types. For example,
collection instead of Array. (#2476)
[client-v2] Added default port for HTTP and improved endpoint string validation - only one allowed. (#2489)
[client-v2] Improved handling error response. (#2511)

Bug Fixes

[client-v2] Fixed metrics to be parsed as Long to avoid integer overflow. Especially for elapsed time in nanos. (#2465)
[client-v2] Fixed a bug with passing some server settings from JDBC to the Client. (#2359)
[jdbc-v2] Fixed DatabaseMetadata to return correct column type. (#2475)
[jdbc-v2] Fixed problem with JDBC URL when Database names that include dash - were parsed wrong. (#2463)
[jdbc-v2] Fixed problem with nested arrays. Previously ArrayValue object was returned as element of a nested array.
After the fix array values contain primitive types. (#2464, #2340)
[jdbc-v2] Fixed JDBC Connection's isValid method returning true all the time. (#2472)
[client-v2] Fixed problem with not closed response object when exception happens. That fixes connections leaking. (#1741)
[jdbc-v2] Fixed a set of issue in StatementImpl. (#2414)
[jdbc-v2] Fixed a set of issues in PreparedStatementImpl. (#2418)
[jdbc-v2] Fixed multiple issues linked to parsing statements in JDBC. (#2450, #2451, #2461, #2500, #2493, #2478)
[jdbc-v2] Fixed result set returning not a DB compliant date/time format. (#2408, #2448)

Release v0.9.0

2025-06-12T03:53:14Z

Important Changes

[repo] Artifacts clickhouse-jdbc:http, clickhouse-jdbc:shaded-all, clickhouse-jdbc:shaded are not published anymore. Use clickhouse-jdbc:all instead. It contains all required shaded libraries except org.slf4j:slf4j-api because it may not be shaded.
[repo] Artifacts jdbc-v2:all, jdbc-v2:http, jdbc-v2:shaded are not published anymore because jdbc-v2 is part of clickhouse-jdbc:all.

Bug Fixes

[jdbc-v2] Fixed parsing SQL with alias in FROM clause when alias name is a keyword (#2427)
[client-v2] Fixed the issue when parameters are not passed if timeout is set. (#2436, #2096)
[jdbc-v2] Fixed parser logging issue. Now parser uses same logger as the driver. (#2428)
[jdbc-v2] Fixed parsing CREATE USER statements. Now parser recognises it correctly. (#2398)
[jdbc-v2] Fixed parsing different CTEs statements. (#2431, #2391, #2443)
[jdbc-v2] Fixed parsing interval values. (#2429)
[repo] Fixed running unit/integration tests in the CI. (#2430)
[jdbc-v2] Fixed parsing parameters when function is in back quotes. (#2422)
[jdbc-v2] Fixed ResultSet#findColumn always returning 0. (#2375)

Misc

[client-v2] Move all default values to ClientConfigurationProperties enum. (#2269)

Docs

[client-v2] Updated documentation of the configuration parameters and how to set server settings and custom HTTP headers.

Release v0.8.6

2025-05-16T19:23:05Z

Improvements

[jdbc-v2] Now using Antlr4 to parse SQL statements to get meta information about it.
Invalid SQL still possible to execute if logic able to get all required information. (#2351)
[jdbc-v2] Now possible to use RowBinaryWriter if enabled by property com.clickhouse.jdbc.internal.DriverProperties.BETA_ROW_BINARY_WRITER.
This works well for batches. Single statements may get no benefits. (#2316)

Bug Fixes

[jdbc-v2] Fixed parsing prepared statement arguments. (#2348)
[jdbc-v2] Fixed parsing role name when it contains -. (#2325)
[jdbc-v2] Fixed failure when INSERT doesn't contain VALUES. (#2283)
[jdbc-v2] Fixed parsing INSERT statement when VALUES is in lower case. (#2354)
[client-v2] Fixed NPE when async operation is request while client was built without an executor.
In this case default JVM executor will be used. (#2355)
[client-v2, jdbc-v2] Fixed conversion of IP addresses. When IPv4 stored as IPv6 it is correctly converted
to Inet6Address. Similar problem fixed for JDBC. (#2342)
[jdbc-v2] Fixed changing DB schema (DB name) on connection when USE statement executed. (#2137)
[client-v2] Fixed serializing POJO with primitive boolean fields. (#2248)