JDBC driver

- The biggest differences is that unsigned types are mapped to java types for better portability.

**String Types**

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Compatible with V1 JDBC Type (V2) Java Class (V2) JDBC Type (V1) Java Class (V1)|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | String ✅ VARCHAR java.lang.String VARCHAR java.lang.String|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | FixedString ✅ VARCHAR java.lang.String VARCHAR java.lang.String | | | | | | | | | | | | | | | | | |

- `FixedString` is read as is in both versions. For example `FixedString(10)` for `'John'` will be read as `'John\0\0\0\0\0\0\0\0\0'`.
- When `PreparedStatement#setBytes` is used it will be converted to `unhex('<hex_string>')` and then read as `String`.
- Strings are stored in UTF-8 encoding.

**Date/Time Types**

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Compatible with V1 JDBC Type (V2) Java Class (V2) JDBC Type (V1) Java Class (V1)|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Date ❌ DATE java.sql.Date DATE java.time.LocalDate|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Date32 ❌ DATE java.sql.Date DATE java.time.LocalDate|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | DateTime ❌ TIMESTAMP java.sql.Timestamp TIMESTAMP java.time.OffsetDateTime|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | DateTime64 ❌ TIMESTAMP java.sql.Timestamp TIMESTAMP java.time.OffsetDateTime|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Time ✅ TIME java.sql.Time new type/not supported new type/not supported|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Time64 ✅ TIME java.sql.Time new type/not supported new type/not supported | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

- `Time` and `Time64` are supported in V2 only as new types.
- `DateTime` and `DateTime64` are mapped to `java.sql.Timestamp` for better compatibility with JDBC.

**Enum Types**

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Compatible with V1 JDBC Type (V2) Java Class (V2) JDBC Type (V1) Java Class (V1)|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Enum ✅ VARCHAR java.lang.String OTHER java.lang.String|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Enum8 ✅ VARCHAR java.lang.String OTHER java.lang.String|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Enum16 ✅ VARCHAR java.lang.String OTHER java.lang.String | | | | | | | | | | | | | | | | | | | | | | | |

**Nested Types**

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Compatible with V1 JDBC Type (V2) Java Class (V2) JDBC Type (V1) Java Class (V1)|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Array ❌ ARRAY java.sql.Array ARRAY Object[] or array of primitive types|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Tuple ❌ OTHER Object[] STRUCT java.sql.Struct|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Map ❌ JAVA\_OBJECT java.util.Map STRUCT java.util.Map|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Nested ❌ ARRAY java.sql.Array STRUCT java.sql.Struct | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

- In V2 `Array` is mapped to `java.sql.Array` by default to be compatible with JDBC. This is also done to give more information about returned array value. Useful for type inference.
- In V2 `Array` implements `getResultSet()` method to return `java.sql.ResultSet` with the same content as the original array.
- V1 uses `STRUCT` for `Map` but returns `java.util.Map` object always. V2 fixes this by mapping `Map` to `JAVA_OBJECT`.
- V1 uses `STRUCT` for `Tuple` but returns `List<Object>` object always. V2 maps `Tuple` to `OTHER` and returns `Object[]` by default.
- V2 introduces `com.clickhouse.data.Tuple#Tuple` to write tuples. It simplifies determining if value is a tuple or and array.
- `PreparedStatement#setBytes` and `ResultSet#getBytes` cannot be used with collection types. These methods are designed to work with binary strings.
- Normally `java.sql.Array` is used to write and read Array types. JDBC driver has full support for this.
- V2 `Nested` is mapped to `Array` and presents it as array of tuples.
- V2 has partial support for `java.sql.Struct` because it very similar to Array type and doesn't support key-value pairs. `Struct` can be used to write `Tuple` values.

**Geo Types**

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Compatible with V1 JDBC Type (V2) Java Class (V2) JDBC Type (V1) Java Class (V1)|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Point ✅ OTHER double[] OTHER double[]|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Ring ✅ OTHER double[][] OTHER double[][]|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Polygon ✅ OTHER double[][][] OTHER double[][][]|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | MultiPolygon ✅ OTHER double[][][][] OTHER double[][][][] | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

**Nullable and LowCardinality Types**

- `Nullable` and `LowCardinality` are special types that wrap other types.
- No changes are made to these types in V2.

**Special Types**