JDBC driver

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

v0.8+

Note

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

## Environment requirements[​](#environment-requirements "Direct link to Environment requirements")

- [OpenJDK](https://openjdk.java.net) version >= 8

### Setup[​](#setup "Direct link to Setup")

- Maven- Gradle (Kotlin)- Gradle

```
<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.9.8</version>
    <classifier>all</classifier>
</dependency>
```

```
// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation("com.clickhouse:clickhouse-jdbc:0.9.8:all")
```

```
// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation 'com.clickhouse:clickhouse-jdbc:0.9.8:all'
```

If you are using JDBC driver within an application that requires jar to be added to the classpath, you need to add download the jar from:

- [Maven Central](https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc) and add it to the classpath
  - starting from version `0.9.4` there is an artifact <https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all>
  - use qualifier `all` to get the jar with all shaded dependencies included.
- or from official repository [here](https://github.com/ClickHouse/clickhouse-java/releases)

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

**Driver Class**: `com.clickhouse.jdbc.ClickHouseDriver`

Note

`com.clickhouse.jdbc.ClickHouseDriver` is a facade class for the new and old JDBC implementations. It uses the new JDBC implementation by default.
You can use the old JDBC implementation by setting the `clickhouse.jdbc.v1` **system** property to `true`. This property should be set before calling
Driver class.

Alternative way to switch between version is to use Driver classes of each version directly:

- `com.clickhouse.jdbc.Driver` is new JDBC implementation (V2).
- `com.clickhouse.jdbc.DriverV1` is old JDBC implementation (V1).

**URL Syntax**: `jdbc:(ch|clickhouse)[:<protocol>]://endpoint[:port][/<database>][?param1=value1&param2=value2][#tag1,tag2,...]`, for example:

- `jdbc:clickhouse:http://localhost:8123`
- `jdbc:clickhouse:https://localhost:8443?ssl=true`

There are a few things to note about the URL syntax:

- **only** one endpoint is allowed in the URL
- protocol should be specified when it isn't the default one - 'HTTP'
- port should be specified when it isn't the default one '8123'
- driver don't guess the protocol from the port, you need to specify it explicitly
- `ssl` parameter isn't required when protocol is specified.

### Connection Properties[​](#connection-properties "Direct link to Connection Properties")

Main configuration parameters are defined in the [java client](/docs/integrations/language-clients/java/client#client-configuration). They should be passed
as is to the driver. Driver has some own properties that aren't part of the client configuration they're listed below.

**Driver properties**:

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Property Default Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `disable_frameworks_detection` `true` Disable frameworks detection for User-Agent|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `jdbc_ignore_unsupported_values` `false` Suppresses `SQLFeatureNotSupportedException` where is doesn't affect the driver work| `clickhouse.jdbc.v1` `false` Use older JDBC implementation instead of new JDBC|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `default_query_settings` `null` Allows passing of default query settings with query operations|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `jdbc_resultset_auto_close` `true` Automatically closes `ResultSet` when `Statement` is closed| `beta.row_binary_for_simple_insert` `false` Use `PreparedStatement` implementation based on `RowBinary` writer. Works only for `INSERT INTO ... VALUES` queries.| `jdbc_resultset_auto_close` `true` Automatically closes `ResultSet` when `Statement` is closed| `jdbc_use_max_result_rows` `false` Enables using server property `max_result_rows` to limit number of rows returned by query. When enabled, overrides user-set overflow mode. See JavaDoc for details.| `jdbc_sql_parser` `JAVACC` Configures which SQL parser to use. Choices: `ANTLR4`, `ANTLR4_PARAMS_PARSER`, `JAVACC`.| `remember_last_set_roles` `true` Remember last set roles for the connection. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Server Settings

All server settings should be prefixed with `clickhouse_setting_` (same as for the client [configuration](/docs/integrations/language-clients/java/client#server-settings)).

```
Properties config = new Properties();
config.setProperty("user", "default");
config.setProperty("password", getPassword());

// set server setting
config.put(ClientConfigProperties.serverSetting("allow_experimental_time_time64_type"), "1");

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", config);
```

**Example configuration**:

```
Properties properties = new Properties();
properties.setProperty("user", "default");
properties.setProperty("password", getPassword());
properties.setProperty("client_name", "my-app-01"); // when http protocol is used it will be `http_user_agent` in the query log but not `client_name`.

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);
```

what will be equivalent to the following JDBC URL:

```
jdbc:ch:http://localhost:8123/?user=default&password=password&client_name=my-app-01 
// credentials shoud be passed in `Properties`. Here it is just for example.
```

Note: no need to url encode JDBC URL or properties, they will be automatically encoded.

### Client Identification[​](#client-identification "Direct link to Client Identification")

There are two ways to identify application originated a request: set `com.clickhouse.client.api.ClientConfigProperties#CLIENT_NAME` via
connection properties or use `java.sql.Connection#setClientInfo(String name, String value)` method.

```
Properties properties = new Properties();
properties.setProperty(ClientConfigProperties.CLIENT_NAME.getKey(), "my-app-01");
Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);
```

```
conn.setClientInfo(com.clickhouse.jdbc.ClientInfoProperties.APPLICATION_NAME.getKey(), "my-app-01");
```

Both ways will result in the following `http_user_agent` value in the query log:

```
my-app-01/1.0 jdbc-v2/0.9.7 clickhouse-java-v2/0.9.6 (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4
```

**Note:** We recommend using `app_name/version` format for `client_name` property because it helps to identify the application in the query log.

### Operation Identification[​](#operation-identification "Direct link to Operation Identification")

JDBC driver generates `query_id` for each operation (Currently it is included in server exceptions).