Skip to content

Commit f07e7a0

Browse files
author
Paultagoras
committed
Docs cleanup
1 parent dabef88 commit f07e7a0

File tree

1 file changed

+46
-20
lines changed
  • docs/en/integrations/language-clients/java

1 file changed

+46
-20
lines changed

‎docs/en/integrations/language-clients/java/jdbc-v2.md

Lines changed: 46 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,32 @@ import CodeBlock from '@theme/CodeBlock';
1616
`clickhouse-jdbc` implements the standard JDBC interface using [client-v2](/docs/en/integrations/language-clients/java/client-v2.md).
1717
We recommend using [client-v2](/docs/en/integrations/language-clients/java/client-v2.md) directly if performance/direct access is critical.
1818

19+
## Changes from 0.7.x
20+
In 0.8 we tried to make the driver more strictly follow the JDBC specification, so there are some removed features that may affect you:
21+
22+
| Old Feature | Notes |
23+
|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
24+
| Transaction Support | Early versions of the driver only **simulated** transaction support, which could have unexpected results. |
25+
| Response Column Renaming | ResultSets were mutable - for efficiency sake they're now read-only |
26+
| Multi-Statement SQL | Multi-statement support was only **simulated**, now it strictly follows 1:1 |
27+
| Named Parameters | Not part of the JDBC spec |
28+
| Stream-based PreparedStatements | Early version of the driver allowed for non-jdbc usage of PreparedStatements - if you desire such options, we recommend looking at [Client-V2](/docs/en/integrations/language-clients/java/client-v2.md) and its [examples](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2). |
29+
30+
### Handling Dates, Times, and Timezones
31+
java.sql.Date, java.sql.Time, and java.sql.Timestamp can complicate how Timezones are calculated - though they're of course supported,
32+
you may want to consider using the [java.time](https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html) package for new code. [ZonedDateTime](https://docs.oracle.com/javase/8/docs/api/java/time/ZonedDateTime.html) and
33+
[OffsetDateTime](https://docs.oracle.com/javase/8/docs/api/java/time/OffsetDateTime.html) are great replacements for java.sql.Timestamp,
34+
and [LocalDateTime](https://docs.oracle.com/javase/8/docs/api/java/time/LocalDateTime.html) could be used for java.sql.Date and java.sql.Time (though the JDBC driver will assume local
35+
timezone if no calendar is provided).
36+
37+
:::note
38+
`Date` is stored without timezone, while `DateTime` is stored with timezone. This can lead to unexpected results if you're not careful.
39+
:::
40+
1941
## Environment requirements
2042

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

23-
2445
### Setup
2546

2647
<Tabs groupId="jdbc-base-dependencies">
@@ -71,20 +92,13 @@ Where possible methods will return an `SQLFeatureNotSupportedException` if the f
7192
| Property | Default | Description |
7293
|----------------------------------|---------|----------------------------------------------------------------|
7394
| `disable_frameworks_detection` | `true` | Disable frameworks detection for User-Agent |
74-
| `jdbc_ignore_unsupported_values` | `false` | Suppresses SQLFeatureNotSupportedException |
95+
| `jdbc_ignore_unsupported_values` | `false` | Suppresses `SQLFeatureNotSupportedException` |
7596
| `clickhouse.jdbc.v1` | `false` | Use JDBC-V1 instead of JDBC-V2 |
7697
| `default_query_settings` | `null` | Allows passing of default query settings with query operations |
7798

7899
## Supported data types
79100

80-
JDBC Driver supports same data formats as the client library does.
81-
82-
:::note
83-
- AggregatedFunction - :warning: does not support `SELECT * FROM table ...`
84-
- Decimal - `SET output_format_decimal_trailing_zeros=1` in 21.9+ for consistency
85-
- Enum - can be treated as both string and integer
86-
- UInt64 - mapped to `long` (in client-v1)
87-
:::
101+
JDBC Driver supports the same data formats as the underlying [client](/docs/en/integrations/language-clients/java/client-v2.md).
88102

89103
## Creating Connection
90104

@@ -123,17 +137,29 @@ try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (?
123137
ps.executeBatch(); // stream everything on-hand into ClickHouse
124138
}
125139
```
126-
## Migrating from 0.7.x
127-
In general we tried to make the driver more strictly follow the JDBC specification, so there are some changes that may affect you:
128-
129-
| Old Feature | Notes |
130-
|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
131-
| Transaction Support | Early versions of the driver only **simulated** transaction support, which could have unexpected results. |
132-
| Response Column Renaming | ResultSets were read/write - for efficiency sake they're now read-only |
133-
| Multi-Statement SQL | Statements would split multi-statements and execute, now it strictly follows 1:1 |
134-
| Named Parameters | |
135-
| Stream-based PreparedStatements | Early version of the driver allowed for non-jdbc usage of PreparedStatements - if you desire such options, we recommend looking to [Client-V2](/docs/en/integrations/language-clients/java/client-v2.md). |
136140

141+
## Hikari
142+
143+
```java showLineNumbers
144+
// connection pooling won't help much in terms of performance,
145+
// because the underlying implementation has its own pool.
146+
// for example: HttpURLConnection has a pool for sockets
147+
HikariConfig poolConfig = new HikariConfig();
148+
poolConfig.setConnectionTimeout(5000L);
149+
poolConfig.setMaximumPoolSize(20);
150+
poolConfig.setMaxLifetime(300_000L);
151+
poolConfig.setDataSource(new ClickHouseDataSource(url, properties));
152+
153+
try (HikariDataSource ds = new HikariDataSource(poolConfig);
154+
Connection conn = ds.getConnection();
155+
Statement s = conn.createStatement();
156+
ResultSet rs = s.executeQuery("SELECT * FROM system.numbers LIMIT 3")) {
157+
while (rs.next()) {
158+
// handle row
159+
log.info("Integer: {}, String: {}", rs.getInt(1), rs.getString(1));//Same column but different types
160+
}
161+
}
162+
```
137163

138164

139165
## More Information

0 commit comments

Comments
 (0)