diff --git a/docs/en/integrations/language-clients/java/client-v1.md b/docs/en/integrations/language-clients/java/client-v1.md index 98bd2a4cddf..f472371e191 100644 --- a/docs/en/integrations/language-clients/java/client-v1.md +++ b/docs/en/integrations/language-clients/java/client-v1.md @@ -1,11 +1,3 @@ ---- -sidebar_label: Client V1 -sidebar_position: 3 -keywords: [clickhouse, java, client, integrate] -description: Java ClickHouse Connector v1 -slug: /en/integrations/java/client-v1 ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; diff --git a/docs/en/integrations/language-clients/java/client-v2.md b/docs/en/integrations/language-clients/java/client-v2.md index a4b97ec203c..3bf2582b232 100644 --- a/docs/en/integrations/language-clients/java/client-v2.md +++ b/docs/en/integrations/language-clients/java/client-v2.md @@ -1,8 +1,8 @@ --- -sidebar_label: Client V2 +sidebar_label: Client 0.8+ sidebar_position: 2 keywords: [clickhouse, java, client, integrate] -description: Java ClickHouse Connector v2 +description: Java ClickHouse Connector 0.8+ slug: /en/integrations/java/client-v2 --- @@ -12,7 +12,12 @@ import CodeBlock from '@theme/CodeBlock'; # Java Client (V2) -Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/docs/en/interfaces/http). The library provides its own API to send requests to a server. The library also provides tools to work with different binary data formats (RowBinary* & Native*). +Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/docs/en/interfaces/http). +The library provides its own API to send requests to a server. The library also provides tools to work with different binary data formats (RowBinary* & Native*). + +:::note +If you're looking for a prior version of the java client docs, please see [here](/docs/en/integrations/language-clients/java/client-v1.md). +::: ## Setup diff --git a/docs/en/integrations/language-clients/java/index.md b/docs/en/integrations/language-clients/java/index.md index 687abe48943..1bc49e4221a 100644 --- a/docs/en/integrations/language-clients/java/index.md +++ b/docs/en/integrations/language-clients/java/index.md @@ -11,9 +11,8 @@ import CodeBlock from '@theme/CodeBlock'; # Java Clients Overview -- [Client-V2](./client-v2.md) -- [Client-V1 (Old)](./client-v1.md) -- [JDBC Driver](./jdbc-driver.md) +- [Client 0.8+](./client-v2.md) +- [JDBC 0.8+](./jdbc-v2.md) - [R2DBC Driver](./r2dbc.md) ## ClickHouse Client diff --git a/docs/en/integrations/language-clients/java/jdbc-driver.md b/docs/en/integrations/language-clients/java/jdbc-v1.md similarity index 93% rename from docs/en/integrations/language-clients/java/jdbc-driver.md rename to docs/en/integrations/language-clients/java/jdbc-v1.md index 7c2a07ed0e6..41ace159793 100644 --- a/docs/en/integrations/language-clients/java/jdbc-driver.md +++ b/docs/en/integrations/language-clients/java/jdbc-v1.md @@ -1,11 +1,3 @@ ---- -sidebar_label: JDBC Driver -sidebar_position: 4 -keywords: [clickhouse, java, jdbc, driver, integrate] -description: ClickHouse JDBC driver -slug: /en/integrations/java/jdbc-driver ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; @@ -16,7 +8,7 @@ import CodeBlock from '@theme/CodeBlock'; `clickhouse-jdbc` implements the standard JDBC interface. Being built on top of [clickhouse-client](/docs/en/integrations/sql-clients/sql-console), it provides additional features like custom type mapping, transaction support, and standard synchronous `UPDATE` and `DELETE` statements, etc., so that it can be easily used with legacy applications and tools. :::note - Latest JDBC (0.7.2) version uses Client-V1 +Latest JDBC (0.7.2) version uses Client-V1 ::: `clickhouse-jdbc` API is synchronous, and generally, it has more overheads(e.g., SQL parsing and type mapping/conversion, etc.). Consider [clickhouse-client](/docs/en/integrations/sql-clients/sql-console) when performance is critical or if you prefer a more direct way to access ClickHouse. @@ -121,14 +113,14 @@ Note: please refer to [JDBC specific configuration](https://github.com/ClickHous ## Supported data types -JDBC Driver supports same data formats as client library does. +JDBC Driver supports same data formats as client library does. :::note - AggregatedFunction - :warning: does not support `SELECT * FROM table ...` - Decimal - `SET output_format_decimal_trailing_zeros=1` in 21.9+ for consistency - Enum - can be treated as both string and integer -- UInt64 - mapped to `long` (in client-v1) -::: +- UInt64 - mapped to `long` (in client-v1) + ::: ## Creating Connection @@ -160,7 +152,7 @@ try (Connection conn = dataSource.getConnection(...); :::note - Use `PreparedStatement` instead of `Statement` -::: + ::: It's easier to use but slower performance compare to input function (see below): @@ -194,7 +186,7 @@ try (PreparedStatement ps = conn.prepareStatement( ### Insert with placeholders -This option is recommended only for small inserts because it would require a long SQL expression (that will be parsed on client side and it will consume CPU & Memory): +This option is recommended only for small inserts because it would require a long SQL expression (that will be parsed on client side and it will consume CPU & Memory): ```java showLineNumbers try (PreparedStatement ps = conn.prepareStatement("insert into mytable values(trim(?),?,?)")) { @@ -272,10 +264,10 @@ try (PreparedStatement stmt = conn.prepareStatement( ## Configuring HTTP library -The ClickHouse JDBC connector supports three HTTP libraries: [HttpClient](https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpClient.html), [HttpURLConnection](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/HttpURLConnection.html), and [Apache HttpClient](https://hc.apache.org/httpcomponents-client-5.2.x/). +The ClickHouse JDBC connector supports three HTTP libraries: [`HttpClient`](https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpClient.html), [`HttpURLConnection`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/HttpURLConnection.html), and [Apache `HttpClient`](https://hc.apache.org/httpcomponents-client-5.2.x/). :::note -HttpClient is only supported in JDK 11 or above. +`HttpClient` is only supported in JDK 11 or above. ::: The JDBC driver uses `HttpClient` by default. You can change the HTTP library used by the ClickHouse JDBC connector by setting the following property: @@ -286,11 +278,11 @@ properties.setProperty("http_connection_provider", "APACHE_HTTP_CLIENT"); Here is a full list of the corresponding values: -| Property Value | HTTP Library | -| ------------------- | ----------------- | -| HTTP_CLIENT | HttpClient | -| HTTP_URL_CONNECTION | HttpURLConnection | -| APACHE_HTTP_CLIENT | Apache HttpClient | +| Property Value | HTTP Library | +|---------------------|---------------------| +| HTTP_CLIENT | `HttpClient` | +| HTTP_URL_CONNECTION | `HttpURLConnection` | +| APACHE_HTTP_CLIENT | Apache `HttpClient` |
@@ -300,16 +292,16 @@ To establish a secure JDBC connection to ClickHouse using SSL, you need to confi ## SSL Properties -| Name | Default Value | Optional Values | Description | -| ------------------ | ------------- | --------------- | ---------------------------------------------------------------------------- | -| `ssl` | false | true, false | Whether to enable SSL/TLS for the connection | -| `sslmode` | strict | strict, none | Whether to verify SSL/TLS certificate | -| `sslrootcert` | | | Path to SSL/TLS root certificates | -| `sslcert` | | | Path to SSL/TLS certificate | -| `sslkey` | | | RSA key in PKCS#8 format | -| `key_store_type` | | JKS, PKCS12 | Specifies the type or format of the KeyStore/Truststore file | -| `trust_store` | | | Path to the Truststore file | -| `key_store_password` | | | Password needed to access the KeyStore file specified in the KeyStore config | +| Name | Default Value | Optional Values | Description | +| ------------------ | ------------- | --------------- |----------------------------------------------------------------------------------| +| `ssl` | false | true, false | Whether to enable SSL/TLS for the connection | +| `sslmode` | strict | strict, none | Whether to verify SSL/TLS certificate | +| `sslrootcert` | | | Path to SSL/TLS root certificates | +| `sslcert` | | | Path to SSL/TLS certificate | +| `sslkey` | | | RSA key in PKCS#8 format | +| `key_store_type` | | JKS, PKCS12 | Specifies the type or format of the `KeyStore`/`TrustStore` file | +| `trust_store` | | | Path to the `TrustStore` file | +| `key_store_password` | | | Password needed to access the `KeyStore` file specified in the `KeyStore` config | These properties ensure that your Java application communicates with the ClickHouse server over an encrypted connection, enhancing data security during transmission. diff --git a/docs/en/integrations/language-clients/java/jdbc-v2.md b/docs/en/integrations/language-clients/java/jdbc-v2.md new file mode 100644 index 00000000000..5276e40149a --- /dev/null +++ b/docs/en/integrations/language-clients/java/jdbc-v2.md @@ -0,0 +1,238 @@ +--- +sidebar_label: JDBC 0.8+ +sidebar_position: 4 +keywords: [clickhouse, java, jdbc, driver, integrate] +description: ClickHouse JDBC driver +slug: /en/integrations/java/jdbc-v2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + + +# JDBC Driver + +`clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/docs/en/integrations/language-clients/java/client-v2.md). +We recommend using the latest [java client](/docs/en/integrations/language-clients/java/client-v2.md) directly if performance/direct access is critical. + +:::note +If you're looking for a prior version of the JDBC driver docs, please see [here](/docs/en/integrations/language-clients/java/jdbc-v1.md). +::: + +## Changes from 0.7.x +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](/docs/en/integrations/language-clients/java/client-v2.md) 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 + +- [OpenJDK](https://openjdk.java.net) version >= 8 + +### Setup + + + + +```xml + + + com.clickhouse + clickhouse-jdbc + 0.8.0 + shaded-all + +``` + + + + +```kotlin +// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc +implementation("com.clickhouse:clickhouse-jdbc:0.8.0:shaded-all") +``` + + + +```groovy +// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc +implementation 'com.clickhouse:clickhouse-jdbc:0.8.0:shaded-all' +``` + + + + +## Configuration + +**Driver Class**: `com.clickhouse.jdbc.ClickHouseDriver` + +**URL Syntax**: `jdbc:(ch|clickhouse)[:]://endpoint1[,endpoint2,...][/][?param1=value1¶m2=value2][#tag1,tag2,...]`, for example: + +- `jdbc:clickhouse:http://localhost:8123` +- `jdbc:clickhouse:https://localhost:8443?ssl=true` + +**Connection Properties**: + +Beyond standard JDBC properties, the driver supports the ClickHouse-specific properties offered by the underlying [java client](/docs/en/integrations/language-clients/java/client-v2.md). +Where possible methods will return an `SQLFeatureNotSupportedException` if the feature is not supported. Other custom properties include: + +| Property | Default | Description | +|----------------------------------|---------|----------------------------------------------------------------| +| `disable_frameworks_detection` | `true` | Disable frameworks detection for User-Agent | +| `jdbc_ignore_unsupported_values` | `false` | Suppresses `SQLFeatureNotSupportedException` | +| `clickhouse.jdbc.v1` | `false` | Use older JDBC implementation instead of new JDBC | +| `default_query_settings` | `null` | Allows passing of default query settings with query operations | + +## Supported data types + +JDBC Driver supports the same data formats as the underlying [java client](/docs/en/integrations/language-clients/java/client-v2.md). + +### Handling Dates, Times, and Timezones +`java.sql.Date`, `java.sql.Time`, and `java.sql.Timestamp` can complicate how Timezones are calculated - though they're of course supported, +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. + +## Creating Connection + +```java +String url = "jdbc:ch://my-server:8123/system"; + +Properties properties = new Properties(); +DataSource dataSource = new DataSource(url, properties);//DataSource or DriverManager are the main entry points +try (Connection conn = dataSource.getConnection()) { +... // do something with the connection +``` + +## Supplying Credentials and Settings + +```java showLineNumbers +String url = "jdbc:ch://localhost:8123?jdbc_ignore_unsupported_values=true&socket_timeout=10"; + +Properties info = new Properties(); +info.put("user", "default"); +info.put("password", "password"); +info.put("database", "some_db"); + +//Creating a connection with DataSource +DataSource dataSource = new DataSource(url, info); +try (Connection conn = dataSource.getConnection()) { +... // do something with the connection +} + +//Alternate approach using the DriverManager +try (Connection conn = DriverManager.getConnection(url, info)) { +... // do something with the connection +} +``` + +## Simple Statement + +```java showLineNumbers + +try (Connection conn = dataSource.getConnection(...); + Statement stmt = conn.createStatement()) { + ResultSet rs = stmt.executeQuery("select * from numbers(50000)"); + while(rs.next()) { + // ... + } +} +``` + +## Insert + +```java showLineNumbers +try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (?, ?)")) { + ps.setString(1, "test"); // id + ps.setObject(2, LocalDateTime.now()); // timestamp + ps.addBatch(); + ... + ps.executeBatch(); // stream everything on-hand into ClickHouse +} +``` + +## `HikariCP` + +```java showLineNumbers +// connection pooling won't help much in terms of performance, +// because the underlying implementation has its own pool. +// for example: HttpURLConnection has a pool for sockets +HikariConfig poolConfig = new HikariConfig(); +poolConfig.setConnectionTimeout(5000L); +poolConfig.setMaximumPoolSize(20); +poolConfig.setMaxLifetime(300_000L); +poolConfig.setDataSource(new ClickHouseDataSource(url, properties)); + +try (HikariDataSource ds = new HikariDataSource(poolConfig); + Connection conn = ds.getConnection(); + Statement s = conn.createStatement(); + ResultSet rs = s.executeQuery("SELECT * FROM system.numbers LIMIT 3")) { + while (rs.next()) { + // handle row + log.info("Integer: {}, String: {}", rs.getInt(1), rs.getString(1));//Same column but different types + } +} +``` + +## More Information +For more information, see our [GitHub repository](https://github.com/ClickHouse/clickhouse-java) and [Java Client documentation](/docs/en/integrations/language-clients/java/client-v2.md). + + +## Troubleshooting +### Logging +The driver uses [slf4j](https://www.slf4j.org/) for logging, and will use the first available implementation on the `classpath`. + +### Resolving JDBC Timeout on Large Inserts + +When performing large inserts in ClickHouse with long execution times, you may encounter JDBC timeout errors like: + +```plaintext +Caused by: java.sql.SQLException: Read timed out, server myHostname [uri=https://hostname.aws.clickhouse.cloud:8443] +``` +These errors can disrupt the data insertion process and affect system stability. To address this issue you may need to adjust a few timeout settings in the client's OS. + +#### Mac OS + +On Mac OS, the following settings can be adjusted to resolve the issue: + +- `net.inet.tcp.keepidle`: 60000 +- `net.inet.tcp.keepintvl`: 45000 +- `net.inet.tcp.keepinit`: 45000 +- `net.inet.tcp.keepcnt`: 8 +- `net.inet.tcp.always_keepalive`: 1 + +#### Linux + +On Linux, the equivalent settings alone may not resolve the issue. Additional steps are required due to the differences in how Linux handles socket keep-alive settings. Follow these steps: + +1. Adjust the following Linux kernel parameters in `/etc/sysctl.conf` or a related configuration file: + + - `net.inet.tcp.keepidle`: 60000 + - `net.inet.tcp.keepintvl`: 45000 + - `net.inet.tcp.keepinit`: 45000 + - `net.inet.tcp.keepcnt`: 8 + - `net.inet.tcp.always_keepalive`: 1 + - `net.ipv4.tcp_keepalive_intvl`: 75 + - `net.ipv4.tcp_keepalive_probes`: 9 + - `net.ipv4.tcp_keepalive_time`: 60 (You may consider lowering this value from the default 300 seconds) + +2. After modifying the kernel parameters, apply the changes by running the following command: + +```shell +sudo sysctl -p +``` + +After Setting those settings, you need to ensure that your client enables the Keep Alive option on the socket: + +```java +properties.setProperty("socket_keepalive", "true"); +``` \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index be28ce970e3..355e3666778 100644 --- a/sidebars.js +++ b/sidebars.js @@ -582,7 +582,8 @@ const sidebars = { // "en/integrations/language-clients/java/index", "en/integrations/language-clients/java/client-v2", "en/integrations/language-clients/java/client-v1", - "en/integrations/language-clients/java/jdbc-driver", + "en/integrations/language-clients/java/jdbc-v2", + "en/integrations/language-clients/java/jdbc-v1", "en/integrations/language-clients/java/r2dbc" ] },