Skip to content

[docs-java-client] Client V2 Configuration Docs #2707

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Nov 5, 2024
Merged

[docs-java-client] Client V2 Configuration Docs #2707

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
32d8ab9
Added client configuration docs and SSL authentication docs for Clien…
chernser Oct 16, 2024
fb04d83
added new configuration parameters in client-v2
chernser Nov 1, 2024
29a7deb
Merge branch 'main' into java_client_docs_update
chernser Nov 1, 2024
d9a1a95
updated wording for some configuration methods
chernser Nov 4, 2024
87d68f4
Merge branch 'main' into java_client_docs_update
chernser Nov 4, 2024
a2d0fbc
updated wording for some configuration methods
chernser Nov 4, 2024
0839073
fixed a few comments
chernser Nov 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/en/integrations/language-clients/java/client-v1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Java client library to communicate with a DB server thru its protocols. Current
<dependency>
<groupId>com.clickhouse</groupId>
<artifactId>clickhouse-http-client</artifactId>
<version>0.6.5</version>
<version>0.7.1</version>
</dependency>
```

Expand All @@ -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")
```
</TabItem>
<TabItem value="gradle" label="Gradle">

```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'
```

</TabItem>
Expand Down
119 changes: 115 additions & 4 deletions docs/en/integrations/language-clients/java/client-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Java client library to communicate with a DB server through its protocols. The c
<dependency>
<groupId>com.clickhouse</groupId>
<artifactId>client-v2</artifactId>
<version>0.6.5</version>
<version>0.7.1</version>
</dependency>
```

Expand All @@ -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")
```
</TabItem>
<TabItem value="gradle" label="Gradle">

```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'
```

</TabItem>
Expand All @@ -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 setting user name password by calling `setUsername(String)` and `setPassword(String)`:
```java showLineNumbers
Client client = new Client.Builder()
.addEndpoint("https://clickhouse-cloud-instance:8443/")
.setUsername(user)
.setPassword(password)
.build();
```

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/")
.setAccessToken(userAccessToken)
.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:
```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

Expand All @@ -71,6 +113,63 @@ 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`.<br />- `host` - IP or hostname of a server.<br />- `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 the client configuration option.<br /> - `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 |
| 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.<br /> - `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.<br /> - `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.<br /> - `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.<br /> - `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.<br /> - `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.<br /> - `host` - proxy host name or IP Address.<br /> - `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.<br /> - `pass` - password | Sets user credentials to authenticate with a proxy. |
| setExecutionTimeout(long timeout, ChronoUnit timeUnit) | - `timeout` - timeout in some time unit.<br /> - `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` - 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.<br /> - `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.<br /> - `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.<br /> - `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.<br /> - `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. |


## Common Definitions

### ClickHouseFormat
Expand Down Expand Up @@ -265,6 +364,12 @@ Configuration options for insert operations.

<dt>setInputStreamCopyBufferSize(int size)</dt>
<dd>Copy buffer size. The buffer is used during write operations to copy data from user provided input stream to an output stream.</dd>
<dt>serverSetting(String name, String value)</dt>
<dd>Sets individual server settings for an operation</dd>
<dt>serverSetting(String name, Collection values)</dt>
<dd>Sets individual server settings with multiple values for an operation. Items of the collection should `String` values</dd>
<dt>setDBRoles(Collection dbRoles)</dt>
<dd>Sets DB roles to be set before executing an operation. Items of the collection should be `String` values</dd>
</dl>

### InsertResponse
Expand Down Expand Up @@ -436,6 +541,12 @@ Configuration options for query operations.
<dd>Server timezone (see client config) will be used to parse date/time types in the result of an operation. Default `false`</dd>
<dt>setUseTimeZone(String timeZone)</dt>
<dd>Requests server to use `timeZone` for time conversion. See <a href="/docs/en/operations/settings/settings#session_timezone" target="_blank">session_timezone</a>.</dd>
<dt>serverSetting(String name, String value)</dt>
<dd>Sets individual server settings for an operation</dd>
<dt>serverSetting(String name, Collection values)</dt>
<dd>Sets individual server settings with multiple values for an operation. Items of the collection should `String` values</dd>
<dt>setDBRoles(Collection dbRoles)</dt>
<dd>Sets DB roles to be set before executing an operation. Items of the collection should be `String` values</dd>
</dl>

### QueryResponse
Expand Down
15 changes: 9 additions & 6 deletions docs/en/integrations/language-clients/java/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,12 +100,12 @@ Table of features of the clients:
| Connection Pool |✔ |✔ | When Apache HTTP Client used |
| Named Parameters |✔ |✔ | |
| Retry on failure |✔ |✔ | |
| Failover |✗ |✔ | |
| Load-balancing |✗ |✔ | |
| Failover |✗ |✔ | will be in v2 |
| Load-balancing |✗ |✔ | will be in v2 |
| 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 |✔ |✔ | |


Expand All @@ -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 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)
Loading