From 32d8ab9a16f1b1f2e3e5b4e0e97e6947dbca2340 Mon Sep 17 00:00:00 2001 From: Sergey Chernov Date: Wed, 16 Oct 2024 12:05:34 -0700 Subject: [PATCH 1/5] Added client configuration docs and SSL authentication docs for Client V2 --- .../language-clients/java/client-v2.md | 99 ++++++++++++++++++- 1 file changed, 98 insertions(+), 1 deletion(-) diff --git a/docs/en/integrations/language-clients/java/client-v2.md b/docs/en/integrations/language-clients/java/client-v2.md index ec4dcda2e77..7db1bd509f7 100644 --- a/docs/en/integrations/language-clients/java/client-v2.md +++ b/docs/en/integrations/language-clients/java/client-v2.md @@ -62,7 +62,49 @@ Example: .build(); ``` -`Client` is `AutoCloseable` and should be closed when not needed anymore. +`Client` is `AutoCloseable` and should be closed when not needed anymore. + +### 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 by a password requires to `setUsername()` and `setPassword()`: +```java showLineNumbers + Client client = new Client.Builder() + .addEndpoint("https://clickhouse-cloud-instance:8443/") + .setUsername(user) + .setPassword(password) + .build(); +``` + +Authentication by an access token requires to `setAccessToken()`: +```java showLineNumbers + Client client = new Client.Builder() + .addEndpoint("https://clickhouse-cloud-instance:8443/") + .setAccessToken(userAccessToken) + .build(); +``` + +Authentication by a SSL Client Certificate require to `setUsername()`, enable SSL Authentication `useSSLAuthentication`, `setClientCertificate()` and `setClientKey`: +```java showLineNumbers +Client client = new Client.Builder() + .useSSLAuthentication(true) + .setUsername("some_user") + .setClientCertificate("some_user.crt") + .setClientKey("some_user.key") +``` + +:::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: +- 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"]}`) + +::: + ## Configuration @@ -71,6 +113,61 @@ Major configuration parameters are defined in one scope (client or operation) an Configuration is defined during client creation. See `com.clickhouse.client.api.Client.Builder`. +## Client Configuration + +| Configuration Method | Arguments | Description | +|---------------------------------------|:-----------------------------------------------|:--------------------------------------------| +| addEndpoint(String endpoint) | - `enpoint` - URL formatted a server address. | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. | +| addEndpoint(Protocol protocol, String host, int port, boolean secure) | - `protocol` - connection protocol `com.clickhouse.client.api.enums.Protocol#HTTP`.
- `host` - IP or hostname of a server.
- `secure` - if communication should use secure version of the protocol (HTTPs) | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. | +| setOption(String key, String value) | - `key` - String key of an option.
- `value` - String value of an option | Sets raw value of client options. Useful when reading configuration from properties files. It helps to avoid calling corresponding builder methods. | +| setUsername(String username) | - `username` - User's username to use while authentication | Sets username for an authentication method that is selected by further configuration | +| setPassword(String password) | - `password` - secret value for password authentication | Sets a secret for password authentication and effectively selects as authentication method | +| setAccessToken(String accessToken) | - `accessToken` - String representation of an access token | Sets an access token to authenticate witha sets corresponding authentication method | +| useSSLAuthentication(boolean useSSLAuthentication) | - `useSSLAuthentication` - flag that indicates if SSL auth should be used | Sets SSL Client Certificate as an authentication method | +| enableConnectionPool(boolean enable) | - `enable` - flag that indicates if the option should be enabled | Sets if a connection pool is enabled | +| setConnectTimeout(long timeout, ChronoUnit unit) | - `timeout` - timeout in some time unit.
- `unit` - time unit of the `timeout` | Sets connection initiation timeout for any outgoing connection. This affects time wait on getting socket connect. | +| setConnectionRequestTimeout(long timeout, ChronoUnit unit) | - `timeout` - timeout in some time unit.
- `unit` - time unit of the `timeout` | Sets connection request timeout. This take effect only for getting connection from a pool. | +| setMaxConnections(int maxConnections) | - `maxConnections` - number of connections | Sets how many connections can a client open to each server endpoint. | +| setConnectionTTL(long timeout, ChronoUnit unit) | - `timeout` - timeout in some time unit.
- `unit` - time unit of the `timeout` | Sets connection TTL after which connection will be considered as not active | +| setKeepAliveTimeout(long timeout, ChronoUnit unit) | - `timeout` - timeout in some time unit.
- `unit` - time unit of the `timeout` | Sets HTTP connection keep-alive timeout. This option may be used to disable Keep-Alive by setting timeout to zero - `0` | +| setConnectionReuseStrategy(ConnectionReuseStrategy strategy) | - `strategy` - enum `com.clickhouse.client.api.ConnectionReuseStrategy` constant | Selects which strategy connection pool should use: `LIFO` if connection should be reused as soon as they are returned to a pool or `FIFO` to use connection in the order they become available (returned connection are not used immediately). | +| setSocketTimeout(long timeout, ChronoUnit unit) | - `timeout` - timeout in some time unit.
- `unit` - time unit of the `timeout` | Sets socket timeout that affects read and write operations | +| setSocketRcvbuf(long size) | - `size` - size in bytes | Sets TCP socket receive buffer. This buffer out of the JVM memory. | +| setSocketSndbuf(long size) | - `size` - size in bytes | Sets TCP socket receive buffer. This buffer out of the JVM memory. | +| setSocketKeepAlive(boolean value) | - `value` - flag that indicates if option should be enabled. | Sets option `SO_KEEPALIVE` for every TCP socket created by the client. TCP Keep Alive enables mechanism that will check liveness of the connection and will help to detect abruptly terminated ones. | +| setSocketTcpNodelay(boolean value) | - `value` - flag that indicates if option should be enabled. | Sets option `SO_NODELAY` for every TCP socket created by the client. This TCP option will make socket to push data as soon as possible. | +| setSocketLinger(int secondsToWait) | - `secondsToWait` - number of seconds. | Set linger time for every TCP socket created by the client. | +| compressServerResponse(boolean enabled) | - `enabled` - flag that indicates if the option should be enabled | Sets if server should compress its responses. | +| compressClientRequest(boolean enabled) | - `enabled` - flag that indicates if the option should be enabled | Sets if client should compress its requests. | +| useHttpCompression(boolean enabled) | - `enabled` - flag that indicates if the option should be enabled | Sets if HTTP compression should be used for client/server communications if corresponding options are enabled | +| setLZ4UncompressedBufferSize(int size) | - `size` - size in bytes | Sets size of a buffer that will receive uncompressed portion of a data stream. If buffer is underestimated - a new one will be created and corresponding warning will be present in logs. | +| setDefaultDatabase(String database) | - `database` - name of a database | Sets default database. | +| addProxy(ProxyType type, String host, int port) | - `type` - proxy type.
- `host` - proxy host name or IP Address.
- `port` - proxy port | Sets proxy to be used for communication with a server. Setting proxy is required if proxy requires authentication. | +| setProxyCredentials(String user, String pass) | - `user` - proxy username.
- `pass` - password | Sets user credentials to authenticate with a proxy. | +| setExecutionTimeout(long timeout, ChronoUnit timeUnit) | - `timeout` - timeout in some time unit.
- `timeUnit` - time unit of the `timeout` | Sets maximum execution timeout for queries | +| setHttpCookiesEnabled(boolean enabled) | `enabled` - flag that indicates if the option should be enabled | Set if HTTP cookies should be remembered and sent to server back. | +| setSSLTrustStore(String path) | `path` - file path on local (client side) system | Sets if client should use SSL truststore for server host validation. | +| setSSLTrustStorePassword(String password) | `password` - secret value | Sets password to be used to unlock SSL truststore specified by `setSSLTrustStore(String path)` | +| setSSLTrustStoreType(String type) | `type` - truststore type name | Sets type of the truststore specified by `setSSLTrustStore(String path)`. | +| setRootCertificate(String path) | `path` - file path on local (client side) system | Sets if client should use specified root (CA) certificate for server host to validation. | +| setClientCertificate(String path) | `path` - file path on local (client side) system | Sets client certificate path to be used while initiating SSL connection and to be used by SSL authentication | +| setClientKey(String path) | `path` - file path on local (client side) system | Sets client private key to be used for encrypting SSL communication with a server. | +| useServerTimeZone(boolean useServerTimeZone) | `useServerTimeZone` - flag that indicates if the option should be enabled | Sets if client should use server timezone when decoding DateTime and Date column values. If enabled then server timezone should be set by `setServerTimeZone(String timeZone)` | +| useTimeZone(String timeZone) | `timeZone` - string value of java valid timezone ID (see `java.time.ZoneId`) | Sets if specified timezone should be used when decoding DateTime and Date column values. Will override server timezone | +| setServerTimeZone(String timeZone) | `timeZone` - string value of java valid timezone ID (see `java.time.ZoneId`) | Sets server side timezone. UTC timezone will be used by default. | +| useAsyncRequests(boolean async) | `async` - flag that indicates if the option should be enabled. | Sets if client should execute request in a separate thread. Disabled by default because application knows better how to organize multithreaded tasks and running tasks in separate thread do not help with performance. | +| setSharedOperationExecutor(ExecutorService executorService) | `executorService` - instance of executor service. | Sets executor service for operation tasks. | +| setClientNetworkBufferSize(int size) | - `size` - size in bytes | Sets size of a buffer in application memory space that is used to copy data back-and-forth between socket and application. Greater reduces system calls to TCP stack, but affects how much memory is spent on every connection. This buffer is also subject for GC because connections are shortlive. Also keep in mind that allocating big continious block of memory might be a problem. | +| retryOnFailures(ClientFaultCause ...causes) | - `causes` - array of causes that causes retry | Set if client should retry on certain faults. This option is useful to avoid some infrequent problems like staled connection. | +| setMaxRetries(int maxRetries) | - `maxRetries` - number of retries | Sets maximum number of retries for failures defined by `retryOnFailures(ClientFaultCause ...causes)` | +| allowBinaryReaderToReuseBuffers(boolean reuse) | - `reuse` - flag that indicates if the option should be enabled | Most datasets contain numeric data encoded as small byte sequences. By default reader will allocate required buffer, read data into it and then transform into a target Number class. That may cause significant GC preasure because of many small objects are being allocated and released. If this option is enabled then reader will use preallocated buffers to do numbers transcoding. It is safe because each reader has own set of buffers and readers are used by one thread. | +| httpHeader(String key, String value) | - `key` - HTTP header key.
- `value` - string value of the header. | Sets value for a single HTTP header. Previous value is overriden.| +| httpHeader(String key, Collection values) | - `key` - HTTP header key.
- `values` - list of string values. | Sets values for a single HTTP header. Previous value is overriden.| +| httpHeaders(Map headers) | - `header` - map with HTTP headers and their values. | Sets multiple HTTP header values at a time. | +| serverSetting(String name, String value) | - `name` - name of a query level setting.
- `value` - string value of the setting. | Sets query level setting to be sent along with every request. Operation settings may override it. See [Query Level Settings](/docs/en/operations/settings/query-level) for more information. | +| serverSetting(String name, Collection values) | - `name` - name of a query level setting.
- `values` - string values of the setting. | Sets query level setting values to be sent along with every request. Operation settings may be override it. This method is useful to set settings with multiple values, for example [roles](/docs/en/interfaces/http#setting-role-with-query-parameters) | + + ## Common Definitions ### ClickHouseFormat From fb04d83b05eed58a8ba4eb3b27231c6ae4bcd9ed Mon Sep 17 00:00:00 2001 From: Sergey Chernov Date: Fri, 1 Nov 2024 14:21:40 -0700 Subject: [PATCH 2/5] added new configuration parameters in client-v2 --- .../language-clients/java/client-v2.md | 14 ++++++++++++++ .../en/integrations/language-clients/java/index.md | 10 +++++----- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/en/integrations/language-clients/java/client-v2.md b/docs/en/integrations/language-clients/java/client-v2.md index 7db1bd509f7..5abe6846eb9 100644 --- a/docs/en/integrations/language-clients/java/client-v2.md +++ b/docs/en/integrations/language-clients/java/client-v2.md @@ -166,6 +166,8 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. | httpHeaders(Map headers) | - `header` - map with HTTP headers and their values. | Sets multiple HTTP header values at a time. | | serverSetting(String name, String value) | - `name` - name of a query level setting.
- `value` - string value of the setting. | Sets query level setting to be sent along with every request. Operation settings may override it. See [Query Level Settings](/docs/en/operations/settings/query-level) for more information. | | serverSetting(String name, Collection values) | - `name` - name of a query level setting.
- `values` - string values of the setting. | Sets query level setting values to be sent along with every request. Operation settings may be override it. This method is useful to set settings with multiple values, for example [roles](/docs/en/interfaces/http#setting-role-with-query-parameters) | +| columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy) | - `strategy` - implementation of a column-field matching strategy | Sets custom strategy to be used for matching DTO class fields and DB columns when registering DTO. | +| useHTTPBasicAuth(boolean useBasicAuth) | - `useBasicAuth` - flag that indicates if the option should be enabled | Sets if basic HTTP authentication should be used for user-password authentication. Default is enabled. Using this type of authentication resolves issues with passwords containing special characters that cannot be transferred over HTTP headers. | ## Common Definitions @@ -362,6 +364,12 @@ Configuration options for insert operations.
setInputStreamCopyBufferSize(int size)
Copy buffer size. The buffer is used during write operations to copy data from user provided input stream to an output stream.
+
serverSetting(String name, String value)
+
Sets individual server settings for an operation
+
serverSetting(String name, Collection values)
+
Sets individual server settings with multiple values for an operation. Items of the collection should `String` values
+
setDBRoles(Collection dbRoles)
+
Sets DB roles to be set before executing an operation. Items of the collection should be `String` values
### InsertResponse @@ -533,6 +541,12 @@ Configuration options for query operations.
Server timezone (see client config) will be used to parse date/time types in the result of an operation. Default `false`
setUseTimeZone(String timeZone)
Requests server to use `timeZone` for time conversion. See session_timezone.
+
serverSetting(String name, String value)
+
Sets individual server settings for an operation
+
serverSetting(String name, Collection values)
+
Sets individual server settings with multiple values for an operation. Items of the collection should `String` values
+
setDBRoles(Collection dbRoles)
+
Sets DB roles to be set before executing an operation. Items of the collection should be `String` values
### QueryResponse diff --git a/docs/en/integrations/language-clients/java/index.md b/docs/en/integrations/language-clients/java/index.md index 410e5cf6442..ca7af8e6df0 100644 --- a/docs/en/integrations/language-clients/java/index.md +++ b/docs/en/integrations/language-clients/java/index.md @@ -101,12 +101,12 @@ Table of features of the clients: | Connection Pool |✔ |✔ | When Apache HTTP Client used | | Named Parameters |✔ |✔ | | | Retry on failure |✔ |✔ | | -| Failover |✗ |✔ | | -| Load-balancing |✗ |✔ | | +| Failover |✗ |✔ | under discussion. (https://github.com/ClickHouse/clickhouse-java/issues/1838) | +| Load-balancing |✗ |✔ | under discussion. (https://github.com/ClickHouse/clickhouse-java/issues/1838) | | Server auto-discovery |✗ |✔ | | -| Log Comment |✗ |✔ | | -| Session Roles |✗ |✔ | will be in V2 | -| SSL Client Authentication |✗ |✔ | will be in V2 | +| Log Comment |✔ |✔ | | +| Session Roles |✔ |✔ | | +| SSL Client Authentication |✔ |✔ | | | Session timezone |✔ |✔ | | From d9a1a95f5528e11c78fa31650bcc10df47fdd447 Mon Sep 17 00:00:00 2001 From: Sergey Chernov Date: Mon, 4 Nov 2024 11:25:08 -0800 Subject: [PATCH 3/5] updated wording for some configuration methods --- .../language-clients/java/client-v1.md | 6 +++--- .../language-clients/java/client-v2.md | 14 +++++++------- .../en/integrations/language-clients/java/index.md | 9 ++++++--- .../language-clients/java/jdbc-driver.md | 8 ++++---- .../en/integrations/language-clients/java/r2dbc.md | 2 +- 5 files changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/en/integrations/language-clients/java/client-v1.md b/docs/en/integrations/language-clients/java/client-v1.md index 4c6a6bbef14..dac7376b6ed 100644 --- a/docs/en/integrations/language-clients/java/client-v1.md +++ b/docs/en/integrations/language-clients/java/client-v1.md @@ -26,7 +26,7 @@ Java client library to communicate with a DB server thru its protocols. Current com.clickhouse clickhouse-http-client - 0.6.5 + 0.7.1 ``` @@ -35,14 +35,14 @@ Java client library to communicate with a DB server thru its protocols. Current ```kotlin // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-http-client -implementation("com.clickhouse:clickhouse-http-client:0.6.5") +implementation("com.clickhouse:clickhouse-http-client:0.7.1") ``` ```groovy // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-http-client -implementation 'com.clickhouse:clickhouse-http-client:0.6.5' +implementation 'com.clickhouse:clickhouse-http-client:0.7.1' ``` diff --git a/docs/en/integrations/language-clients/java/client-v2.md b/docs/en/integrations/language-clients/java/client-v2.md index 5abe6846eb9..d7712c8a0a6 100644 --- a/docs/en/integrations/language-clients/java/client-v2.md +++ b/docs/en/integrations/language-clients/java/client-v2.md @@ -26,7 +26,7 @@ Java client library to communicate with a DB server through its protocols. The c com.clickhouse client-v2 - 0.6.5 + 0.7.1 ``` @@ -35,14 +35,14 @@ Java client library to communicate with a DB server through its protocols. The c ```kotlin // https://mvnrepository.com/artifact/com.clickhouse/client-v2 -implementation("com.clickhouse:client-v2:0.6.5") +implementation("com.clickhouse:client-v2:0.7.1") ``` ```groovy // https://mvnrepository.com/artifact/com.clickhouse/client-v2 -implementation 'com.clickhouse:client-v2:0.6.5' +implementation 'com.clickhouse:client-v2:0.7.1' ``` @@ -119,7 +119,7 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. |---------------------------------------|:-----------------------------------------------|:--------------------------------------------| | addEndpoint(String endpoint) | - `enpoint` - URL formatted a server address. | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. | | addEndpoint(Protocol protocol, String host, int port, boolean secure) | - `protocol` - connection protocol `com.clickhouse.client.api.enums.Protocol#HTTP`.
- `host` - IP or hostname of a server.
- `secure` - if communication should use secure version of the protocol (HTTPs) | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. | -| setOption(String key, String value) | - `key` - String key of an option.
- `value` - String value of an option | Sets raw value of client options. Useful when reading configuration from properties files. It helps to avoid calling corresponding builder methods. | +| setOption(String key, String value) | - `key` - String key of the client configuration option.
- `value` - String value of the option | Sets raw value of client options. Useful when reading configuration from properties files. | | setUsername(String username) | - `username` - User's username to use while authentication | Sets username for an authentication method that is selected by further configuration | | setPassword(String password) | - `password` - secret value for password authentication | Sets a secret for password authentication and effectively selects as authentication method | | setAccessToken(String accessToken) | - `accessToken` - String representation of an access token | Sets an access token to authenticate witha sets corresponding authentication method | @@ -158,14 +158,14 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. | useAsyncRequests(boolean async) | `async` - flag that indicates if the option should be enabled. | Sets if client should execute request in a separate thread. Disabled by default because application knows better how to organize multithreaded tasks and running tasks in separate thread do not help with performance. | | setSharedOperationExecutor(ExecutorService executorService) | `executorService` - instance of executor service. | Sets executor service for operation tasks. | | setClientNetworkBufferSize(int size) | - `size` - size in bytes | Sets size of a buffer in application memory space that is used to copy data back-and-forth between socket and application. Greater reduces system calls to TCP stack, but affects how much memory is spent on every connection. This buffer is also subject for GC because connections are shortlive. Also keep in mind that allocating big continious block of memory might be a problem. | -| retryOnFailures(ClientFaultCause ...causes) | - `causes` - array of causes that causes retry | Set if client should retry on certain faults. This option is useful to avoid some infrequent problems like staled connection. | +| retryOnFailures(ClientFaultCause ...causes) | - `causes` - enum constant of `com.clickhouse.client.api.ClientFaultCause` | Sets what fault causes should be considered as recoverable and on what a request should be retried. | | setMaxRetries(int maxRetries) | - `maxRetries` - number of retries | Sets maximum number of retries for failures defined by `retryOnFailures(ClientFaultCause ...causes)` | | allowBinaryReaderToReuseBuffers(boolean reuse) | - `reuse` - flag that indicates if the option should be enabled | Most datasets contain numeric data encoded as small byte sequences. By default reader will allocate required buffer, read data into it and then transform into a target Number class. That may cause significant GC preasure because of many small objects are being allocated and released. If this option is enabled then reader will use preallocated buffers to do numbers transcoding. It is safe because each reader has own set of buffers and readers are used by one thread. | | httpHeader(String key, String value) | - `key` - HTTP header key.
- `value` - string value of the header. | Sets value for a single HTTP header. Previous value is overriden.| | httpHeader(String key, Collection values) | - `key` - HTTP header key.
- `values` - list of string values. | Sets values for a single HTTP header. Previous value is overriden.| | httpHeaders(Map headers) | - `header` - map with HTTP headers and their values. | Sets multiple HTTP header values at a time. | -| serverSetting(String name, String value) | - `name` - name of a query level setting.
- `value` - string value of the setting. | Sets query level setting to be sent along with every request. Operation settings may override it. See [Query Level Settings](/docs/en/operations/settings/query-level) for more information. | -| serverSetting(String name, Collection values) | - `name` - name of a query level setting.
- `values` - string values of the setting. | Sets query level setting values to be sent along with every request. Operation settings may be override it. This method is useful to set settings with multiple values, for example [roles](/docs/en/interfaces/http#setting-role-with-query-parameters) | +| serverSetting(String name, String value) | - `name` - name of a query level setting.
- `value` - string value of the setting. | Sets what settings to pass to server along with each query. Individual operation settings may override it. The [List of settings](/docs/en/operations/settings/query-level) | +| serverSetting(String name, Collection values) | - `name` - name of a query level setting.
- `values` - string values of the setting. |Sets what settings to pass to server along with each query. Individual operation settings may override it. The [List of settings](/docs/en/operations/settings/query-level). This method is useful to set settings with multiple values, for example [roles](/docs/en/interfaces/http#setting-role-with-query-parameters) | | columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy) | - `strategy` - implementation of a column-field matching strategy | Sets custom strategy to be used for matching DTO class fields and DB columns when registering DTO. | | useHTTPBasicAuth(boolean useBasicAuth) | - `useBasicAuth` - flag that indicates if the option should be enabled | Sets if basic HTTP authentication should be used for user-password authentication. Default is enabled. Using this type of authentication resolves issues with passwords containing special characters that cannot be transferred over HTTP headers. | diff --git a/docs/en/integrations/language-clients/java/index.md b/docs/en/integrations/language-clients/java/index.md index 7b1e80fe860..63e4626db66 100644 --- a/docs/en/integrations/language-clients/java/index.md +++ b/docs/en/integrations/language-clients/java/index.md @@ -100,8 +100,8 @@ Table of features of the clients: | Connection Pool |✔ |✔ | When Apache HTTP Client used | | Named Parameters |✔ |✔ | | | Retry on failure |✔ |✔ | | -| Failover |✗ |✔ | under discussion. (https://github.com/ClickHouse/clickhouse-java/issues/1838) | -| Load-balancing |✗ |✔ | under discussion. (https://github.com/ClickHouse/clickhouse-java/issues/1838) | +| Failover |✗ |✔ | will be in v2 | +| Load-balancing |✗ |✔ | will be in v2 | | Server auto-discovery |✗ |✔ | | | Log Comment |✔ |✔ | | | Session Roles |✔ |✔ | | @@ -116,4 +116,7 @@ JDBC Drive inherits same features as underlying client implementation. Other JDB - All projects in this repo are tested with all [active LTS versions](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) of ClickHouse. - [Support policy](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md#security-change-log-and-support) - We recommend to upgrade client continuously to not miss security fixes and new improvements -- If you have an issue with migration to v2 API - [create and issue](https://github.com/ClickHouse/clickhouse-java/issues/new?assignees=&labels=v2-feedback&projects=&template=v2-feedback.md&title=) and we will respond! +- If you have an issue with migration to v2 API - [create and issue](https://github.com/ClickHouse/clickhouse-java/issues/new?assignees=&labels=v2-feedback&projects=&template=v2-feedback.md&title=) and we will respond! + + +[ChangeLog](https://github.com/ClickHouse/clickhouse-java/blob/main/CHANGELOG.md) diff --git a/docs/en/integrations/language-clients/java/jdbc-driver.md b/docs/en/integrations/language-clients/java/jdbc-driver.md index 12ad91c4fe5..e2c2b1607c8 100644 --- a/docs/en/integrations/language-clients/java/jdbc-driver.md +++ b/docs/en/integrations/language-clients/java/jdbc-driver.md @@ -16,7 +16,7 @@ import CodeBlock from '@theme/CodeBlock'; `clickhouse-jdbc` implements the standard JDBC interface. Being built on top of [clickhouse-client](/docs/en/integrations/clickhouse-client-local.md), 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.6.5) version uses Client-V1 + Latest JDBC (0.7.1) 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/clickhouse-client-local.md) when performance is critical or if you prefer a more direct way to access ClickHouse. @@ -36,7 +36,7 @@ import CodeBlock from '@theme/CodeBlock'; com.clickhouse clickhouse-jdbc - 0.6.5 + 0.7.1 all @@ -48,7 +48,7 @@ import CodeBlock from '@theme/CodeBlock'; ```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.6.5:all") +implementation("com.clickhouse:clickhouse-jdbc:0.7.1:all") ``` @@ -56,7 +56,7 @@ implementation("com.clickhouse:clickhouse-jdbc:0.6.5: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.6.5:all' +implementation 'com.clickhouse:clickhouse-jdbc:0.7.1:all' ``` diff --git a/docs/en/integrations/language-clients/java/r2dbc.md b/docs/en/integrations/language-clients/java/r2dbc.md index 77518fb8016..ec7926ec427 100644 --- a/docs/en/integrations/language-clients/java/r2dbc.md +++ b/docs/en/integrations/language-clients/java/r2dbc.md @@ -27,7 +27,7 @@ import CodeBlock from '@theme/CodeBlock'; com.clickhouse clickhouse-r2dbc - 0.6.5 + 0.7.1 all From a2d0fbcfab55905b1ab98ebbc4553dfb47a4f6e9 Mon Sep 17 00:00:00 2001 From: Sergey Chernov Date: Mon, 4 Nov 2024 11:34:31 -0800 Subject: [PATCH 4/5] updated wording for some configuration methods --- docs/en/integrations/language-clients/java/client-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/integrations/language-clients/java/client-v2.md b/docs/en/integrations/language-clients/java/client-v2.md index d7712c8a0a6..4f15baa1ae8 100644 --- a/docs/en/integrations/language-clients/java/client-v2.md +++ b/docs/en/integrations/language-clients/java/client-v2.md @@ -158,7 +158,7 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. | useAsyncRequests(boolean async) | `async` - flag that indicates if the option should be enabled. | Sets if client should execute request in a separate thread. Disabled by default because application knows better how to organize multithreaded tasks and running tasks in separate thread do not help with performance. | | setSharedOperationExecutor(ExecutorService executorService) | `executorService` - instance of executor service. | Sets executor service for operation tasks. | | setClientNetworkBufferSize(int size) | - `size` - size in bytes | Sets size of a buffer in application memory space that is used to copy data back-and-forth between socket and application. Greater reduces system calls to TCP stack, but affects how much memory is spent on every connection. This buffer is also subject for GC because connections are shortlive. Also keep in mind that allocating big continious block of memory might be a problem. | -| retryOnFailures(ClientFaultCause ...causes) | - `causes` - enum constant of `com.clickhouse.client.api.ClientFaultCause` | Sets what fault causes should be considered as recoverable and on what a request should be retried. | +| retryOnFailures(ClientFaultCause ...causes) | - `causes` - enum constant of `com.clickhouse.client.api.ClientFaultCause` | Sets recoverable/retriable fault types. | | setMaxRetries(int maxRetries) | - `maxRetries` - number of retries | Sets maximum number of retries for failures defined by `retryOnFailures(ClientFaultCause ...causes)` | | allowBinaryReaderToReuseBuffers(boolean reuse) | - `reuse` - flag that indicates if the option should be enabled | Most datasets contain numeric data encoded as small byte sequences. By default reader will allocate required buffer, read data into it and then transform into a target Number class. That may cause significant GC preasure because of many small objects are being allocated and released. If this option is enabled then reader will use preallocated buffers to do numbers transcoding. It is safe because each reader has own set of buffers and readers are used by one thread. | | httpHeader(String key, String value) | - `key` - HTTP header key.
- `value` - string value of the header. | Sets value for a single HTTP header. Previous value is overriden.| From 0839073582aa11ac9f8bb49e2be425e8d41209ec Mon Sep 17 00:00:00 2001 From: Sergey Chernov Date: Mon, 4 Nov 2024 21:37:18 -0800 Subject: [PATCH 5/5] fixed a few comments --- docs/en/integrations/language-clients/java/client-v2.md | 6 +++--- docs/en/integrations/language-clients/java/index.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/en/integrations/language-clients/java/client-v2.md b/docs/en/integrations/language-clients/java/client-v2.md index 4f15baa1ae8..a560cb6ffcf 100644 --- a/docs/en/integrations/language-clients/java/client-v2.md +++ b/docs/en/integrations/language-clients/java/client-v2.md @@ -68,7 +68,7 @@ Example: 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 to `setUsername()` and `setPassword()`: +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/") @@ -77,7 +77,7 @@ Authentication by a password requires to `setUsername()` and `setPassword()`: .build(); ``` -Authentication by an access token requires to `setAccessToken()`: +Authentication by an access token requires setting access token by calling `setAccessToken(String)`: ```java showLineNumbers Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") @@ -85,7 +85,7 @@ Authentication by an access token requires to `setAccessToken()`: .build(); ``` -Authentication by a SSL Client Certificate require to `setUsername()`, enable SSL Authentication `useSSLAuthentication`, `setClientCertificate()` and `setClientKey`: +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) diff --git a/docs/en/integrations/language-clients/java/index.md b/docs/en/integrations/language-clients/java/index.md index 63e4626db66..39e35c084d6 100644 --- a/docs/en/integrations/language-clients/java/index.md +++ b/docs/en/integrations/language-clients/java/index.md @@ -116,7 +116,7 @@ JDBC Drive inherits same features as underlying client implementation. Other JDB - All projects in this repo are tested with all [active LTS versions](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) of ClickHouse. - [Support policy](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md#security-change-log-and-support) - We recommend to upgrade client continuously to not miss security fixes and new improvements -- If you have an issue with migration to v2 API - [create and issue](https://github.com/ClickHouse/clickhouse-java/issues/new?assignees=&labels=v2-feedback&projects=&template=v2-feedback.md&title=) and we will respond! +- If you have an issue with migration to v2 API - [create an issue](https://github.com/ClickHouse/clickhouse-java/issues/new?assignees=&labels=v2-feedback&projects=&template=v2-feedback.md&title=) and we will respond! [ChangeLog](https://github.com/ClickHouse/clickhouse-java/blob/main/CHANGELOG.md)