Java Client

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/integrations/language-clients/java/client/client.mdx)

v0.8+

Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/docs/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 "Direct link to Setup")

- Maven Central (project web page): <https://mvnrepository.com/artifact/com.clickhouse/client-v2>
- Nightly builds (repository link): <https://central.sonatype.com/repository/maven-snapshots/>
- Old Nightly builds artifactory (repository link): <https://s01.oss.sonatype.org/content/repositories/snapshots/>

  

- Maven- Gradle (Kotlin)- Gradle

```
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>client-v2</artifactId>
    <version>0.9.8</version>
</dependency>
```

```
// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation("com.clickhouse:client-v2:0.9.8")
```

```
// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation 'com.clickhouse:client-v2:0.9.8'
```

  

## Initialization[​](#initialization "Direct link to 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.

Example:

```
 Client client = new Client.Builder()
                .addEndpoint("https://clickhouse-cloud-instance:8443/")
                .setUsername(user)
                .setPassword(password)
                .build();
```

`Client` is `AutoCloseable` and should be closed when not needed anymore.

### Authentication[​](#authentication "Direct link to 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)`:

```
 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)`:

```
 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 certificate and a client key by calling `setUsername(String)`, `useSSLAuthentication(boolean)`, `setClientCertificate(String)` and `setClientKey(String)` accordingly:

```
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 don't 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[​](#configuration "Direct link to Configuration")

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 don't override each other.

Configuration is defined during client creation. See `com.clickhouse.client.api.Client.Builder`.

## Client Configuration[​](#client-configuration "Direct link to Client Configuration")

- Connection & Endpoints- Authentication- Timeouts & Retry- Socket Options- Compression- SSL/Security- Proxy- HTTP & Headers- Server Settings- Timezone- Advanced

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Method Arguments Description Default Key|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `addEndpoint(String endpoint)` `endpoint` - URL formatted server address Adds a server endpoint to list of available servers. Currently only one endpoint is supported. `none` `none`| `addEndpoint(Protocol protocol, String host, int port, boolean secure)` `protocol` - connection protocol `host` - IP or hostname `secure` - use HTTPS Adds a server endpoint to list of available servers. Currently only one endpoint is supported. `none` `none`| `enableConnectionPool(boolean enable)` `enable` - flag to enable/disable Sets if a connection pool is enabled `true` `connection_pool_enabled`| `setMaxConnections(int maxConnections)` `maxConnections` - number of connections Sets how many connections can a client open to each server endpoint. `10` `max_open_connections`| `setConnectionTTL(long timeout, ChronoUnit unit)` `timeout` - timeout value `unit` - time unit Sets connection TTL after which connection will be considered as not active `-1` `connection_ttl`| `setKeepAliveTimeout(long timeout, ChronoUnit unit)` `timeout` - timeout value `unit` - time unit Sets HTTP connection keep-alive timeout. Set to `0` to disable Keep-Alive. - `http_keep_alive_timeout`| `setConnectionReuseStrategy(ConnectionReuseStrategy strategy)` `strategy` - `LIFO` or `FIFO` Selects which strategy connection pool should use `FIFO` `connection_reuse_strategy`| `setDefaultDatabase(String database)` `database` - name of a database Sets default database. `default` `database` | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |