diff --git a/contribute/style-guide.md b/contribute/style-guide.md index b16d26a66d3..4911653d767 100644 --- a/contribute/style-guide.md +++ b/contribute/style-guide.md @@ -251,3 +251,128 @@ should pass. Finally open another PR on the docs repo again to remove the file from the exception list and add it to `sidebars.js` in the appropriate sidebar. +## Client versioning + +### Background + +Docusaurus supports versioning documentation, however it is opinionated and +aimed more at use cases where you have a single product with set releases, or +multiple products with their own releases. + +Due to the fact that we have many different integrations in ClickHouse, each of +which may need versioned documentation, we use the following custom +`ClientVersionDropdown` component for versioning of client documentation: + +```markdown + +``` + +### How to use it + +Versioned folders are structured as follows: + +```text +. +├── client +│ ├── _snippets +│ │ ├── _v0_7.mdx +│ │ └── _v0_8.mdx +│ └── client.mdx +├── index.md +├── jdbc +│ ├── _snippets +│ │ ├── _v0_7.mdx +│ │ └── _v0_8.mdx +│ └── jdbc.mdx +└── r2dbc.md +``` + +* The content for each version is placed in a snippet. For example `_v0_7.mdx` + * Snippets begin with `_` + * Snippets do not contain front-matter + * These snippets import any components they may need (See `_v0_7.mdx` for example) + * They should be .mdx files +* There is a single page for all versions. For example `client.mdx` + * This page contains frontmatter + * It imports the `` component + * It should be a .mdx file + +To use this component, import it into the single page: + +```js +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown' +``` + +Also import the two snippets: + +```js +import v07 from './_v0_7.mdx' +import v08 from './_v0_8.mdx' +``` + +Pass it an array of objects representing versions and their respective snippets: + +```markdown + +``` + +**Note**: The component will display the first item as the 'selected' version, so +it is important to make sure the order of the objects is correct. + +### URL parameters + +If you need to share a link to the page you can do it through URL params: + +```response +/docs/integrations/language-clients/java/client?v=v08 +``` + +When using URL parameters to control which version of documentation is displayed, +there are conventions to follow for reliable functionality. +Here's how the `?v=v08` parameter relates to the snippet selection: + +#### How It Works + +The URL parameter acts as a selector that matches against the `version` property +in your component configuration. For example: + +- URL: `docs/api?v=v08` +- Matches: `version: 'v0.8+'` in your dropdown configuration + +#### Conventions That Work + +- **Simple Version Strings**: Parameters like `?v=v08`, `?v=v07` work by +- matching against stripped versions of your configured version names. + +- **Flexible Matching**: The implementation supports: + - Removing dots: `v0.8` matches `?v=v08` + - Ignoring plus signs: `v0.8+` matches `?v=v08` + - Case-insensitive matching: `v0.8` matches `?v=V08` + +- **Preserving Other Parameters**: Other URL parameters are preserved when +switching versions. + +#### What Won't Work + +- **Partial Matches**: `?v=8` won't match `v0.8` with the default implementation. + +- **Complex Version Strings**: Very complex versions like `?v=v1.2.3-beta.4` +require more sophisticated matching logic. (Reach out to the docs team if required) + +- **Non-Standard Formats**: Version formats not accounted for in the matching +logic might fail. + +#### Best Practices + +1. Keep version strings in consistent formats for predictable results. + +2. Use simplified version parameters in URLs (e.g., `v08` instead of `v0.8.x`). diff --git a/docs/integrations/language-clients/java/client-v1.md b/docs/integrations/language-clients/java/client/_snippets/_v0_7.mdx similarity index 98% rename from docs/integrations/language-clients/java/client-v1.md rename to docs/integrations/language-clients/java/client/_snippets/_v0_7.mdx index 7c46aa250e9..052965fed45 100644 --- a/docs/integrations/language-clients/java/client-v1.md +++ b/docs/integrations/language-clients/java/client/_snippets/_v0_7.mdx @@ -1,19 +1,10 @@ ---- -title: 'Client (0.7.x and earlier)' -description: 'Java client library to communicate with a DB server through its protocols.' -slug: /integrations/language-clients/java/client-v1 ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -# Client (0.7.x and earlier) Java client library to communicate with a DB server through its protocols. Current implementation supports only [HTTP interface](/interfaces/http). The library provides own API to send requests to a server. :::warning Deprecation -This library will be deprecated soon. Use the latest [Java Client](/integrations/language-clients/java/client.md) for new projects +This library will be deprecated soon. Use the latest [Java Client](/integrations/language-clients/java/client/client.mdx) for new projects ::: ## Setup {#setup} diff --git a/docs/integrations/language-clients/java/client.md b/docs/integrations/language-clients/java/client/_snippets/_v0_8.mdx similarity index 96% rename from docs/integrations/language-clients/java/client.md rename to docs/integrations/language-clients/java/client/_snippets/_v0_8.mdx index aafaf24e662..eb2a6a1b187 100644 --- a/docs/integrations/language-clients/java/client.md +++ b/docs/integrations/language-clients/java/client/_snippets/_v0_8.mdx @@ -1,30 +1,14 @@ ---- -sidebar_label: 'Client 0.8+' -sidebar_position: 2 -keywords: ['clickhouse', 'java', 'client', 'integrate'] -description: 'Java ClickHouse Connector 0.8+' -slug: /integrations/language-clients/java/client -title: 'Java Client (0.8+)' ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -# Java Client (0.8+) -Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/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](/integrations/language-clients/java/client-v1.md). -::: +Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/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*). ## Setup {#setup} - Maven Central (project web page): https://mvnrepository.com/artifact/com.clickhouse/client-v2 - Nightly builds (repository link): https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/ - +
@@ -57,9 +41,9 @@ implementation 'com.clickhouse:client-v2:0.8.2' ## Initialization {#initialization} The Client object is initialized by `com.clickhouse.client.api.Client.Builder#build()`. Each client has its own context and no objects are shared between them. -The Builder has configuration methods for convenient setup. +The Builder has configuration methods for convenient setup. -Example: +Example: ```java showLineNumbers Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") @@ -72,9 +56,9 @@ Example: ### Authentication {#authentication} -Authentication is configured per client at the initialization phase. There are three authentication methods supported: by password, by access token, by SSL Client Certificate. +Authentication is configured per client at the initialization phase. There are three authentication methods supported: by password, by access token, by SSL Client Certificate. -Authentication by a password requires setting user name password by calling `setUsername(String)` and `setPassword(String)`: +Authentication by a password requires setting user name password by calling `setUsername(String)` and `setPassword(String)`: ```java showLineNumbers Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") @@ -91,7 +75,7 @@ Authentication by an access token requires setting access token by calling `setA .build(); ``` -Authentication by a SSL Client Certificate require setting username, enabling SSL Authentication, setting a client sertificate and a client key by calling `setUsername(String)`, `useSSLAuthentication(boolean)`, `setClientCertificate(String)` and `setClientKey(String)` accordingly: +Authentication by a SSL Client Certificate require setting username, enabling SSL Authentication, setting a client sertificate and a client key by calling `setUsername(String)`, `useSSLAuthentication(boolean)`, `setClientCertificate(String)` and `setClientKey(String)` accordingly: ```java showLineNumbers Client client = new Client.Builder() .useSSLAuthentication(true) @@ -103,18 +87,18 @@ Client client = new Client.Builder() :::note SSL Authentication may be hard to troubleshoot on production because many errors from SSL libraries provide not enough information. For example, if client certificate and key do not match then server will terminate connection immediately (in case of HTTP it will be connection initiation stage where no HTTP requests are send so no response is sent). -Please use tools like [openssl](https://docs.openssl.org/master/man1/openssl/) to verify certificates and keys: +Please use tools like [openssl](https://docs.openssl.org/master/man1/openssl/) to verify certificates and keys: - check key integrity: `openssl rsa -in [key-file.key] -check -noout` - check client certificate has matching CN for a user: - get CN from an user certificate - `openssl x509 -noout -subject -in [user.cert]` - - verify same value is set in database `select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'` (query will output `auth_params` with something like ` {"common_names":["some_user"]}`) + - verify same value is set in database `select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'` (query will output `auth_params` with something like ` {"common_names":["some_user"]}`) ::: ## Configuration {#configuration} -All settings are defined by instance methods (a.k.a configuration methods) that make the scope and context of each value clear. +All settings are defined by instance methods (a.k.a configuration methods) that make the scope and context of each value clear. Major configuration parameters are defined in one scope (client or operation) and do not override each other. Configuration is defined during client creation. See `com.clickhouse.client.api.Client.Builder`. @@ -181,9 +165,9 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. ### ClickHouseFormat {#clickhouseformat} -Enum of [supported formats](/interfaces/formats). It includes all formats that ClickHouse supports. +Enum of [supported formats](/interfaces/formats). It includes all formats that ClickHouse supports. -* `raw` - user should transcode raw data +* `raw` - user should transcode raw data * `full` - the client can transcode data by itself and accepts a raw data stream * `-` - operation not supported by ClickHouse for this format @@ -329,7 +313,7 @@ client.insert(String tableName, List data) **Parameters** -`tableName` - name of the target table. +`tableName` - name of the target table. `data` - collection DTO (Data Transfer Object) objects. @@ -371,7 +355,7 @@ Configuration options for insert operations. ### InsertResponse {#insertresponse} -Response object that holds result of insert operation. It is only available if the client got response from a server. +Response object that holds result of insert operation. It is only available if the client got response from a server. :::note This object should be closed as soon as possible to release a connection because the connection cannot be re-used until all data of previous response is fully read. @@ -397,13 +381,13 @@ CompletableFuture query(String sqlQuery) **Parameters** -`sqlQuery` - a single SQL statement. The Query is sent as is to a server. +`sqlQuery` - a single SQL statement. The Query is sent as is to a server. `settings` - request settings. **Return value** -Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. +Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. **Examples** @@ -444,15 +428,15 @@ CompletableFuture query(String sqlQuery, Map quer **Parameters** -`sqlQuery` - sql expression with placeholders `{}`. +`sqlQuery` - sql expression with placeholders `{}`. `queryParams` - map of variables to complete the sql expression on server. -`settings` - request settings. +`settings` - request settings. **Return value** -Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. +Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. **Examples** @@ -495,7 +479,7 @@ List queryAll(String sqlQuery) **Return value** -Complete dataset represented by a list of `GenericRecord` objects that provide access in row style for the result data. +Complete dataset represented by a list of `GenericRecord` objects that provide access in row style for the result data. **Examples** @@ -538,7 +522,7 @@ Configuration options for query operations. ### QueryResponse {#queryresponse} -Response object that holds result of query execution. It is only available if the client got a response from a server. +Response object that holds result of query execution. It is only available if the client got a response from a server. :::note This object should be closed as soon as possible to release a connection because the connection cannot be re-used until all data of previous response is fully read. @@ -582,7 +566,7 @@ Returns a `TableSchema` object with list of table columns. ### getTableSchemaFromQuery(String sql) {#gettableschemafromquerystring-sql} -Fetches schema from a SQL statement. +Fetches schema from a SQL statement. **Signatures** @@ -602,8 +586,8 @@ Returns a `TableSchema` object with columns matching the `sql` expression. ### register(Class<?> clazz, TableSchema schema) {#registerclasslt-clazz-tableschema-schema} -Compiles serialization and deserialization layer for the Java Class to use for writing/reading data with `schema`. The method will create a serializer and deserializer for the pair getter/setter and corresponding column. -Column match is found by extracting its name from a method name. For example, `getFirstName` will be for the column `first_name` or `firstname`. +Compiles serialization and deserialization layer for the Java Class to use for writing/reading data with `schema`. The method will create a serializer and deserializer for the pair getter/setter and corresponding column. +Column match is found by extracting its name from a method name. For example, `getFirstName` will be for the column `first_name` or `firstname`. **Signatures** diff --git a/docs/integrations/language-clients/java/client/client.mdx b/docs/integrations/language-clients/java/client/client.mdx new file mode 100644 index 00000000000..eb4df152520 --- /dev/null +++ b/docs/integrations/language-clients/java/client/client.mdx @@ -0,0 +1,23 @@ +--- +sidebar_label: 'Client' +sidebar_position: 2 +keywords: ['clickhouse', 'java', 'client', 'integrate'] +description: 'Java ClickHouse Connector' +slug: /integrations/language-clients/java/client +title: 'Java Client' +--- + +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'; +import v07 from './_snippets/_v0_7.mdx' +import v08 from './_snippets/_v0_8.mdx' + + diff --git a/docs/integrations/language-clients/java/index.md b/docs/integrations/language-clients/java/index.md index 729729f9d33..2f1d92083db 100644 --- a/docs/integrations/language-clients/java/index.md +++ b/docs/integrations/language-clients/java/index.md @@ -11,8 +11,8 @@ import CodeBlock from '@theme/CodeBlock'; # Java Clients Overview -- [Client 0.8+](./client.md) -- [JDBC 0.8+](./jdbc.md) +- [Client 0.8+](./client/client.mdx) +- [JDBC 0.8+](./jdbc/jdbc.mdx) - [R2DBC Driver](./r2dbc.md) ## ClickHouse Client {#clickhouse-client} diff --git a/docs/integrations/language-clients/java/jdbc-v1.md b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_7.mdx similarity index 88% rename from docs/integrations/language-clients/java/jdbc-v1.md rename to docs/integrations/language-clients/java/jdbc/_snippets/_v0_7.mdx index ac6ab4a9dc0..cb7c27b051a 100644 --- a/docs/integrations/language-clients/java/jdbc-v1.md +++ b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_7.mdx @@ -1,15 +1,5 @@ ---- -title: 'JDBC Driver' -description: 'Page describing the JDBC driver for ClickHouse' -slug: /integrations/language-clients/java/jdbc-v1 ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -# JDBC Driver `clickhouse-jdbc` implements the standard JDBC interface. Being built on top of [clickhouse-client](/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. @@ -27,69 +17,69 @@ Latest JDBC (0.7.2) version uses Client-V1 ### Setup {#setup} - - -```xml - - - com.clickhouse - clickhouse-jdbc - 0.7.2 - - shaded-all - -``` - - - - -```kotlin -// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -// use uber jar with all dependencies included, change classifier to http for smaller jar -implementation("com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all") -``` - - - -```groovy -// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -// use uber jar with all dependencies included, change classifier to http for smaller jar -implementation 'com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all' -``` - - + + + ```xml + + + com.clickhouse + clickhouse-jdbc + 0.7.2 + + shaded-all + + ``` + + + + + ```kotlin + // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc + // use uber jar with all dependencies included, change classifier to http for smaller jar + implementation("com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all") + ``` + + + + ```groovy + // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc + // use uber jar with all dependencies included, change classifier to http for smaller jar + implementation 'com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all' + ``` + + Since version `0.5.0`, we are using Apache HTTP Client that's packed the Client. Since there is not a shared version of the package, you need to add a logger as a dependency. - - -```xml - - - org.slf4j - slf4j-api - 2.0.16 - -``` - - - - -```kotlin -// https://mvnrepository.com/artifact/org.slf4j/slf4j-api -implementation("org.slf4j:slf4j-api:2.0.16") -``` - - - -```groovy -// https://mvnrepository.com/artifact/org.slf4j/slf4j-api -implementation 'org.slf4j:slf4j-api:2.0.16' -``` - - + + + ```xml + + + org.slf4j + slf4j-api + 2.0.16 + + ``` + + + + + ```kotlin + // https://mvnrepository.com/artifact/org.slf4j/slf4j-api + implementation("org.slf4j:slf4j-api:2.0.16") + ``` + + + + ```groovy + // https://mvnrepository.com/artifact/org.slf4j/slf4j-api + implementation 'org.slf4j:slf4j-api:2.0.16' + ``` + + ## Configuration {#configuration} @@ -126,7 +116,7 @@ JDBC Driver supports same data formats as client library does. - 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) - ::: +::: ## Creating Connection {#creating-connection} @@ -158,7 +148,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): @@ -355,19 +345,19 @@ On Linux, the equivalent settings alone may not resolve the issue. Additional st 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) +- `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 +```shell +sudo sysctl -p ``` After Setting those settings, you need to ensure that your client enables the Keep Alive option on the socket: @@ -395,4 +385,4 @@ try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.H .query(sql) .executeAndWait(); } -``` +``` \ No newline at end of file diff --git a/docs/integrations/language-clients/java/jdbc.md b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx similarity index 81% rename from docs/integrations/language-clients/java/jdbc.md rename to docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx index 3220a71a47d..5a70168e2ab 100644 --- a/docs/integrations/language-clients/java/jdbc.md +++ b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx @@ -1,24 +1,9 @@ ---- -sidebar_label: 'JDBC 0.8+' -sidebar_position: 4 -keywords: ['clickhouse', 'java', 'jdbc', 'driver', 'integrate'] -description: 'ClickHouse JDBC driver' -slug: /integrations/language-clients/java/jdbc -title: 'JDBC Driver (0.8+)' ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - - -# JDBC Driver (0.8+) - -`clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client.md). -We recommend using the latest [java client](/integrations/language-clients/java/client.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](/integrations/language-clients/java/jdbc-v1.md). +`clickhouse-jdbc` implements the standard JDBC interface using the latest java clientю +We recommend using the latest java client directly if performance/direct access is critical. ::: ## Changes from 0.7.x {#changes-from-07x} @@ -30,7 +15,7 @@ In 0.8 we tried to make the driver more strictly follow the JDBC specification, | 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.md) and its [examples](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2). | +| 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. @@ -43,34 +28,34 @@ In 0.8 we tried to make the driver more strictly follow the JDBC specification, ### Setup {#setup} - - -```xml - - - com.clickhouse - clickhouse-jdbc - 0.8.2 - shaded-all - -``` - - - - -```kotlin -// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -implementation("com.clickhouse:clickhouse-jdbc:0.8.2:shaded-all") -``` - - - -```groovy -// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -implementation 'com.clickhouse:clickhouse-jdbc:0.8.2:shaded-all' -``` - - + + + ```xml + + + com.clickhouse + clickhouse-jdbc + 0.8.2 + shaded-all + + ``` + + + + + ```kotlin + // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc + implementation("com.clickhouse:clickhouse-jdbc:0.8.2:shaded-all") + ``` + + + + ```groovy + // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc + implementation 'com.clickhouse:clickhouse-jdbc:0.8.2:shaded-all' + ``` + + ## Configuration {#configuration} @@ -84,7 +69,7 @@ implementation 'com.clickhouse:clickhouse-jdbc:0.8.2:shaded-all' **Connection Properties**: -Beyond standard JDBC properties, the driver supports the ClickHouse-specific properties offered by the underlying [java client](/integrations/language-clients/java/client.md). +Beyond standard JDBC properties, the driver supports the ClickHouse-specific properties offered by the underlying [java client](/integrations/language-clients/java/client/client.mdx). Where possible methods will return an `SQLFeatureNotSupportedException` if the feature is not supported. Other custom properties include: | Property | Default | Description | @@ -96,7 +81,7 @@ Where possible methods will return an `SQLFeatureNotSupportedException` if the f ## Supported data types {#supported-data-types} -JDBC Driver supports the same data formats as the underlying [java client](/integrations/language-clients/java/client.md). +JDBC Driver supports the same data formats as the underlying [java client](/integrations/language-clients/java/client/client.mdx). ### Handling Dates, Times, and Timezones {#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, @@ -162,7 +147,7 @@ try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (? ``` ## `HikariCP` {#hikaricp} - + ```java showLineNumbers // connection pooling won't help much in terms of performance, // because the underlying implementation has its own pool. @@ -185,7 +170,7 @@ try (HikariDataSource ds = new HikariDataSource(poolConfig); ``` ## More Information {#more-information} -For more information, see our [GitHub repository](https://github.com/ClickHouse/clickhouse-java) and [Java Client documentation](/integrations/language-clients/java/client.md). +For more information, see our [GitHub repository](https://github.com/ClickHouse/clickhouse-java) and [Java Client documentation](/integrations/language-clients/java/client/client.mdx). ## Troubleshooting {#troubleshooting} @@ -217,14 +202,14 @@ On Linux, the equivalent settings alone may not resolve the issue. Additional st 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) + - `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: @@ -236,4 +221,4 @@ After Setting those settings, you need to ensure that your client enables the Ke ```java properties.setProperty("socket_keepalive", "true"); -``` +``` \ No newline at end of file diff --git a/docs/integrations/language-clients/java/jdbc/jdbc.mdx b/docs/integrations/language-clients/java/jdbc/jdbc.mdx new file mode 100644 index 00000000000..9b78e45034a --- /dev/null +++ b/docs/integrations/language-clients/java/jdbc/jdbc.mdx @@ -0,0 +1,23 @@ +--- +sidebar_label: 'JDBC' +sidebar_position: 4 +keywords: ['clickhouse', 'java', 'jdbc', 'driver', 'integrate'] +description: 'ClickHouse JDBC driver' +slug: /integrations/language-clients/java/jdbc +title: 'JDBC Driver' +--- + +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'; +import v07 from './_snippets/_v0_7.mdx' +import v08 from './_snippets/_v0_8.mdx' + + diff --git a/sidebars.js b/sidebars.js index 232758d2a0e..a4c91ef2428 100644 --- a/sidebars.js +++ b/sidebars.js @@ -645,8 +645,8 @@ const sidebars = { id: "integrations/language-clients/java/index" }, // "integrations/language-clients/java/index", - "integrations/language-clients/java/client", - "integrations/language-clients/java/jdbc", + "integrations/language-clients/java/client/client", + "integrations/language-clients/java/jdbc/jdbc", "integrations/language-clients/java/r2dbc" ] }, diff --git a/src/theme/ClientVersionDropdown/ClientVersionDropdown.js b/src/theme/ClientVersionDropdown/ClientVersionDropdown.js new file mode 100644 index 00000000000..b85eef7bea5 --- /dev/null +++ b/src/theme/ClientVersionDropdown/ClientVersionDropdown.js @@ -0,0 +1,163 @@ +import React, {useState, useEffect, useRef} from 'react'; +import Link from '@docusaurus/Link'; +import styles from './styles.module.css' +import ReactDOM from 'react-dom'; +import {useHistory, useLocation} from "react-router-dom"; + +const ClientVersionDropdown = (props) => { + const history = useHistory(); + const location = useLocation(); + const [displayDropdown, setDisplayDropdown] = useState(false); + const [dropdownPosition, setDropdownPosition] = useState({top: 0, left: 0}); + const [selectedVersionIndex, setSelectedVersionIndex] = useState(0); + const buttonRef = useRef(null); + const dropdownRef = useRef(null); + + // Find version from URL parameter on initial load + useEffect(() => { + const searchParams = new URLSearchParams(location.search); + const versionParam = searchParams.get('v'); + + if (versionParam) { + // Find the matching version in our versions array + const foundIndex = props.versions.findIndex(item => + item.version === versionParam || + item.version.replace('.', '') === versionParam || + item.version.toLowerCase().replace(/[^a-z0-9]/g, '') === versionParam.toLowerCase() + ); + + if (foundIndex !== -1) { + setSelectedVersionIndex(foundIndex); + } + } + }, [location.search, props.versions]); + + const onClickHandler = () => { + setDisplayDropdown(!displayDropdown); + }; + + const handleLinkClick = (e, slug, index) => { + e.preventDefault(); + + setTimeout(() => { + setDisplayDropdown(false); + setSelectedVersionIndex(index); + + // Get the version string from the selected version + const versionString = props.versions[index].version; + + // Determine the URL to navigate to + let targetUrl; + if (slug) { + // If slug provided, navigate to that page + targetUrl = slug; + } else { + // Otherwise update the URL parameter on the current page + const searchParams = new URLSearchParams(location.search); + + // Convert the version to a URL-friendly format + const versionParam = versionString.replace(/\./g, '').replace(/\+/g, ''); + + searchParams.set('v', versionParam); + targetUrl = `${location.pathname}?${searchParams.toString()}`; + } + + history.push(targetUrl); + }, 10); + }; + + useEffect(() => { + if (displayDropdown && buttonRef.current) { + const buttonRect = buttonRef.current.getBoundingClientRect(); + setDropdownPosition({ + top: buttonRect.bottom + window.scrollY, + left: buttonRect.left + window.scrollX + }); + } + }, [displayDropdown]); + + useEffect(() => { + const handleClickOutside = (event) => { + if (dropdownRef.current && dropdownRef.current.contains(event.target)) { + if (event.target.tagName === 'A') { + return; + } + } + + if (buttonRef.current && !buttonRef.current.contains(event.target) && + dropdownRef.current && !dropdownRef.current.contains(event.target)) { + setDisplayDropdown(false); + } + }; + + if (displayDropdown) { + document.addEventListener('mousedown', handleClickOutside); + } + + return () => { + document.removeEventListener('mousedown', handleClickOutside); + }; + }, [displayDropdown]); + + const renderDropdown = () => { + if (!displayDropdown) return null; + + const dropdownStyleDynamic = { + top: `${dropdownPosition.top}px`, + left: `${dropdownPosition.left}px`, + }; + + return ReactDOM.createPortal( +
+ {props.versions.map((item, index) => ( + handleLinkClick(e, item.slug, index)} + > + {item.version} + + ))} +
, + document.body + ); + }; + + const selectedVersion = props.versions[selectedVersionIndex]; + + // Get the MDXContent component + const MDXContent = selectedVersion.snippet; + + return ( + <> +
+
+ {selectedVersion.version} +
+ +
+ + {renderDropdown()} + +
+ {MDXContent && typeof MDXContent === 'function' && } +
+ + ); +}; + +export default ClientVersionDropdown; diff --git a/src/theme/ClientVersionDropdown/styles.module.css b/src/theme/ClientVersionDropdown/styles.module.css new file mode 100644 index 00000000000..b110e13f33e --- /dev/null +++ b/src/theme/ClientVersionDropdown/styles.module.css @@ -0,0 +1,73 @@ +/* Styling of the top level container */ + +.dropDownButton { + display: flex; + margin-bottom: 24px; + align-items: center; + width: fit-content; + cursor: pointer; + border-style: solid; + border-width: 1px; + border-radius: 10px; + padding: 0px 15px 0px 10px; +} + +.versionText{ + +} + +/* Styling of the triangle in the dropdown button */ + +.triangle { + position: relative; + display: inline-block; + margin-right: 5px; +} + +.triangle::after { + content: ""; + position: absolute; + top: 50%; + right: -15px; /* Adjust as needed */ + width: 0; + height: 0; + border-left: 5px solid transparent; + border-right: 5px solid transparent; + transform: translateY(-50%); +} + +[data-theme='dark'] .triangle::after { + border-top: 5px solid #ffff; /* Color of triangle */ +} + +[data-theme='light'] .triangle::after { + border-top: 5px solid #000; /* Color of triangle */ +} + +.dropdownItem { + display: block; + padding: 8px 16px; + text-decoration: none; + color: black; +} + +.dropdownItem:hover { + background-color: #f5f5f5; +} + +.dropdownStyleStatic { + position: absolute; + margin-top: 2px; + border-radius: 4px; + box-shadow: 0 2px 10px rgba(0,0,0,0.1); + z-index: 1000; + +} + +[data-theme='dark'] .dropdownStyleStatic { + background-color: #3c3c3c; +} + +[data-theme='light'] .dropdownStyleStatic { + background-color: white; +}