Updated documentation and change log

Author: chernser

CHANGELOG.md

@@ -2,12 +2,19 @@
 
 ### Breaking Changes
 
-- **[jdbc-v2]** Hardcoded server setting `async_insert=0` is removed as well as others. This is done to
-  fix issue with overriding these settings and using client with read-only profiles. The change, first of all, makes
-  driver behavior to follow default what is set on server side (note: starting ClickHouse 26.3 `async_insert` is on by default).
-  In second, this fix changes what number of affected rows returned by method like `java.sql.Statement.executeUpdate(java.lang.String)`.
-  Previously they return more accurate values because insert was synchronous, but in case of asynchronous insert it is not
-  guaranteed anymore (see also https://github.com/ClickHouse/ClickHouse/issues/57768). Read more about asynchronous insert https://clickhouse.com/docs/optimize/asynchronous-inserts.
+- **[jdbc-v2]** The driver no longer hardcodes the server settings `async_insert=0` and `wait_end_of_query=0` on every JDBC
+  connection. This unblocks two scenarios that previously did not work: overriding these settings per connection or per
+  statement, and using the driver against read-only profiles that disallow `SETTINGS` overrides. There are two consequences:
+  - The driver now follows the server-side defaults for these settings (note: starting with ClickHouse 26.3, `async_insert`
+    defaults to `1`). Removing the explicit `wait_end_of_query=0` is a no-op against server defaults but lets users opt in to
+    `wait_end_of_query=1`.
+  - The row count returned by `java.sql.Statement.executeUpdate(java.lang.String)` (and the matching `PreparedStatement`
+    method) is no longer guaranteed to be accurate for INSERT statements when the server runs them asynchronously, and
+    parsing/data errors in the INSERT body may not surface synchronously as a `SQLException`. Previously these were
+    accurate because inserts were forced to be synchronous (see also https://github.com/ClickHouse/ClickHouse/issues/57768).
+    To restore the previous behavior, set `async_insert=0` (or `wait_for_async_insert=1`) per connection or statement.
+    Read more about asynchronous insert: https://clickhouse.com/docs/optimize/asynchronous-inserts.
+
   (https://github.com/ClickHouse/clickhouse-java/issues/2652, https://github.com/ClickHouse/clickhouse-java/issues/2825)
 
 ### New Features

docs/features.md

@@ -76,3 +76,4 @@ Compatibility-sensitive traits:
 - `getString()` formatting for temporal values is stable output: `Date` uses `yyyy-MM-dd`, `DateTime` uses `yyyy-MM-dd HH:mm:ss`, and `DateTime64` preserves fractional precision, all interpreted in server timezone context where applicable.
 - Date and timestamp setters with `Calendar` are timezone-sensitive by design. Preserving the current day-shift and instant-preserving behavior is important for compatibility.
 - `setObject()` temporal behavior is specific and should not drift: `LocalDateTime` and `Instant` are rendered through `fromUnixTimestamp64Nano(...)`, while `Timestamp` and `Date` use quoted textual forms.
+- INSERT result semantics depend on server-side `async_insert` and `wait_for_async_insert`. The driver does not override these settings, so it follows whatever the server profile or user configuration sets. When `async_insert=1` and `wait_for_async_insert=0`, `Statement.executeUpdate(...)` and `PreparedStatement.executeUpdate(...)` may return `0` (or an under-counted value), and parsing/data errors in the INSERT body may not be reported synchronously as a `SQLException`. Set `async_insert=0` (or `wait_for_async_insert=1`) per connection or statement to restore synchronous row counts and error reporting.