Merge pull request #369 from youngsofun/ts

feat: support  java.time and timestamp_tz

Author: youngsofun

README.md

@@ -3,6 +3,11 @@
 ![Apache License 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)
 [![databend-jdbc](https://img.shields.io/maven-central/v/com.databend/databend-jdbc?style=flat-square)](https://central.sonatype.dev/artifact/com.databend/databend-jdbc/0.0.1)
 
+## Highlights
+
+- Databend-specific interfaces to stream files into tables or stages with `loadStreamToTable`, `uploadStream`, and `downloadStream`.
+- Temporal APIs use session timezone to avoid depending on JVM default zone and support modern `java.time`.
+
 ## Prerequisites
 
 The Databend JDBC driver requires Java 8 or later.
@@ -73,36 +78,61 @@ public class Main {
    you can call `while(r.next(){})` to iterate over the result set.
 3. For other SQL such as `create/drop table` non-query type SQL, you can call `statement.execute()` directly.
 
-## JDBC Java type mapping
-The Databend type is mapped to Java type as follows:
 
-| Databend Type | Java Type  |
-|---------------|------------|
-| TINYINT       | Byte       |
-| SMALLINT      | Short      |
-| INT           | Integer    |
-| BIGINT        | Long       |
-| UInt8         | Short      |
-| UInt16        | Integer    |
-| UInt32        | Long       |
-| UInt64        | BigInteger |
-| Float32       | Float      |
-| Float64       | Double     |
-| String        | String     |
-| Date          | String     |
-| TIMESTAMP     | String     |
-| Bitmap        | byte[]     |
-| Array         | String     |
-| Decimal       | BigDecimal |
-| Tuple         | String     |
-| Map           | String     |
-| VARIANT       | String     |
+## Connection Parameters 
 
 For detailed references, please take a look at the following Links:
 
 1. [Connection Parameters](./docs/Connection.md) : detailed documentation about how to use connection parameters in a
    jdbc connection
 
+## JDBC Java type mapping
+The Databend type is mapped to Java type as follows:
+
+| Databend Type | Java Type      |
+|---------------|----------------|
+| TINYINT       | Byte           |
+| SMALLINT      | Short          |
+| INT           | Integer        |
+| BIGINT        | Long           |
+| UInt8         | Short          |
+| UInt16        | Integer        |
+| UInt32        | Long           |
+| UInt64        | BigInteger     |
+| Float32       | Float          |
+| Float64       | Double         |
+| Decimal       | BigDecimal     |
+| String        | String         |
+| Date          | LocalDate      |
+| TIMESTAMP     | ZonedDateTime  |
+| TIMESTAMP_TZ  | OffsetDateTime |
+| Bitmap        | byte[]         |
+| Array         | String         |
+| Tuple         | String         |
+| Map           | String         |
+| VARIANT       | String         |
+
+### Temporal types
+
+we recommend using `java.time` to avoid ambiguity and letting the driver format values via these APIs:
+
+```
+void setObject(int parameterIndex, Object x)
+<T> T getObject(int columnIndex, Class<T> type)
+```
+
+- TIMESTAMP_TZ and TIMESTAMP map to `OffsetDateTime`, `ZonedDateTime`, `Instant` and `LocalDateTime` (TIMESTAMP_TZ can return `OffsetDateTime` but not `ZonedDateTime`).
+- Date maps to `LocalDate`, and `getObject(..., LocalDate.class)` now mirrors what `getDate().toLocalDate()` returns.
+- When parameters do not contain a timezone, Databend uses the session timezone (not the JVM zone) when storing/returning dates on databend-jdbc ≥ 0.4.3 AND databend-query ≥1.2.844.
+- `getString` return the display of default mapping type.
+
+Timestamp/Date are also supported, note that:
+
+- `getTimestamp(int, Calendar cal)` is the same as `getTimestamp(int)` (the cal is omitted) and
+`getObject(int, Instant.classes).toTimestamp()`
+- `setTimestamp(int, Calendar cal)` is diff with `setTimestamp(int)`, the epoch is adjusted according to timezone in cal
+- `setDate`/`getDate` still use the JVM timezone, and `setObject(localDate)` is equivalent to `setDate(Date.valueOf(localDate))`.
+
 
 # Unwrapping to Databend-specific interfaces 
 
@@ -171,4 +201,3 @@ Download a single file in the stage as `InputStream`
 ```
 InputStream downloadStream(String stageName, String filePathInStage) throws SQLException;
 ```
-

databend-client/src/main/java/com/databend/client/data/DatabendDataType.java

@@ -55,6 +55,7 @@ public enum DatabendDataType {
 
     DATE(Types.DATE, DatabendTypes.DATE, false, 10, true, "Date"),
     TIMESTAMP(Types.TIMESTAMP, DatabendTypes.TIMESTAMP, false, 26, true, "DateTime", "TIMESTAMP"),
+    TIMESTAMP_TZ(Types.TIMESTAMP_WITH_TIMEZONE, DatabendTypes.TIMESTAMP, false, 32, true, "TIMESTAMP_TZ"),
 
     ARRAY(Types.ARRAY, DatabendTypes.ARRAY, false, 0, false, "Array"),
     MAP(Types.OTHER, DatabendTypes.MAP, false, 0, false, "Map"),
@@ -119,6 +120,8 @@ public static DatabendDataType getByTypeName(String typeName) {
             return DATE;
         } else if (DatabendTypes.TIMESTAMP.equalsIgnoreCase(typeName)) {
             return TIMESTAMP;
+        } else if (DatabendTypes.TIMESTAMP_TZ.equalsIgnoreCase(typeName)) {
+            return TIMESTAMP_TZ;
         } else if (DatabendTypes.VARIANT.equalsIgnoreCase(typeName)) {
             return VARIANT;
         } else if (DatabendTypes.BITMAP.equalsIgnoreCase(typeName)) {

databend-client/src/main/java/com/databend/client/data/DatabendTypes.java

@@ -32,6 +32,7 @@ public final class DatabendTypes {
     public static final String DATETIME = "datetime";
     public static final String DATETIME64 = "datetime64";
     public static final String TIMESTAMP = "timestamp";
+    public static final String TIMESTAMP_TZ = "timestamp_tz";
     public static final String STRING = "string";
     public static final String STRUCT = "struct";
     public static final String ARRAY = "array";