Skip to content

[Java Doc] Update December 2025 #5012

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
chernser wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[Java Doc] Update December 2025 #5012

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 53 additions & 14 deletions docs/integrations/language-clients/java/jdbc/jdbc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,20 +30,6 @@ import TabItem from '@theme/TabItem';
We recommend using the latest java client directly if performance/direct access is critical.
:::

## Changes from 0.7.x {#changes-from-07x}
In 0.8 we tried to make the driver more strictly follow the JDBC specification, so there are some removed features that may affect you:

| Old Feature | Notes |
|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Transaction Support | Early versions of the driver only **simulated** transaction support, which could have unexpected results. |
| Response Column Renaming | `ResultSet` was mutable - for efficiency sake they're now read-only |
| Multi-Statement SQL | Multi-statement support was only **simulated**, now it strictly follows 1:1 |
| Named Parameters | Not part of the JDBC spec |
| Stream-based `PreparedStatement` | Early version of the driver allowed for non-jdbc usage of `PreparedStatement` - if you desire such options, we recommend looking at the [Java Client](/integrations/language-clients/java/client/client.mdx) and its [examples](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2). |

:::note
`Date` is stored without timezone, while `DateTime` is stored with timezone. This can lead to unexpected results if you're not careful.
:::

## Environment requirements {#environment-requirements}

Expand Down Expand Up @@ -104,6 +90,10 @@ Where possible methods will return an `SQLFeatureNotSupportedException` if the f
| `default_query_settings` | `null` | Allows passing of default query settings with query operations |
| `jdbc_resultset_auto_close` | `true` | Automatically closes `ResultSet` when `Statement` is closed |
| `beta.row_binary_for_simple_insert` | `false` | Use `PreparedStatement` implementation based on `RowBinary` writer. Works only for `INSERT INTO ... VALUES` queries. |
| `jdbc_resultset_auto_close` | `true` | Automatically closes `ResultSet` when `Statement` is closed |
| `jdbc_use_max_result_rows` | `false` | Enables using server property `max_result_rows` to limit number of rows returned by query. When enabled, overrides user-set overflow mode. See JavaDoc for details. |
| `jdbc_sql_parser` | `JAVACC` | Configures which SQL parser to use. Choices: `ANTLR4`, `ANTLR4_PARAMS_PARSER`, `JAVACC`. |


:::note Server Settings

Expand Down Expand Up @@ -131,6 +121,10 @@ JDBC Driver supports the same data formats as the underlying [java client](/inte
you may want to consider using the [java.time](https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html) package. `ZonedDateTime` and
`OffsetDateTime` are both great replacements for java.sql.Timestamp, java.sql.Date, and java.sql.Time.

:::note
`Date` is stored without timezone, while `DateTime` is stored with timezone. This can lead to unexpected results if you're not careful.
:::

## Creating Connection {#creating-connection}

```java
Expand All @@ -142,6 +136,8 @@ try (Connection conn = dataSource.getConnection()) {
... // do something with the connection
```



## Supplying Credentials and Settings {#supplying-credentials-and-settings}

```java showLineNumbers
Expand Down Expand Up @@ -265,6 +261,49 @@ After Setting those settings, you need to ensure that your client enables the Ke
properties.setProperty("socket_keepalive", "true");
```

## Migration Guide {#migration-guide}

### Key Changes {#key-changes}

| Feature | V1 (Old) | V2 (New) |
|---------|----------|----------|
| Transaction Support | Partially supported | Not supported |
| Response Column Renaming | Partially supported | Not supported |
| Multi-Statement SQL | Not supported | Not allowed |
| Named Parameters | Supported | Not supported (not in JDBC spec) |
| Streaming Data With `PreparedStatement` | Supported | Not supported |

- JDBC V2 is implemented to be more lightweight and some features were removed.
- Streaming Data is not supported in JDBC V2 because it is not part of the JDBC spec and Java.
- JDBC V2 expects explicit configuration. No failover defaults.
- Protocol should be specified in the URL. No implicit protocol detection using port numbers.

### Configuration Changes {#configuration-changes}

There are only two enums:
- `com.clickhouse.jdbc.DriverProperties` - the driver own configuration properties.
- `com.clickhouse.client.api.ClientConfigProperties` - the client configuration properties. Client configuration
changes are described in the [Java Client documentation](/integrations/language-clients/java/client/client.mdx#migration_from_v1_config).

Connection properties are parsed in the following way:
- URL is parsed first for properties. They override all other properties.
- Driver properties are not passed to the client.
- Endpoints (host, port, protocol) are parsed from the URL.

Example:
```java
String url = "jdbc:ch://my-server:8443/default?" +
"jdbc_ignore_unsupported_values=true&" +
"socket_rcvbuf=800000";

Properties properties = new Properties();
properties.setProperty("socket_rcvbuf", "900000");
try (Connection conn = DriverManager.getConnection(url, properties)) {
// Connection will use socket_rcvbuf=800000 and jdbc_ignore_unsupported_values=true
// Endpoints: my-server:8443 protocol: http (not secure)
// Database: default
}
```
</Version>

<Version>
Expand Down
Loading