@clickhouse/client 1.18.4-head.f30da83.1 → 1.18.5-head.bccbdcf.1

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.18.4-head.f30da83.1";
+declare const _default: "1.18.5-head.bccbdcf.1";
 export default _default;

package/dist/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = '1.18.4-head.f30da83.1';
+exports.default = '1.18.5-head.bccbdcf.1';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -2,7 +2,7 @@
   "name": "@clickhouse/client",
   "description": "Official JS client for ClickHouse DB - Node.js implementation",
   "homepage": "https://clickhouse.com",
-  "version": "1.18.4-head.f30da83.1",
+  "version": "1.18.5-head.bccbdcf.1",
   "license": "Apache-2.0",
   "keywords": [
     "clickhouse",
@@ -40,7 +40,7 @@
     "build": "rm -rf dist; tsc"
   },
   "dependencies": {
-    "@clickhouse/client-common": "1.18.4-head.f30da83.1"
+    "@clickhouse/client-common": "1.18.5-head.bccbdcf.1"
   },
   "devDependencies": {
     "simdjson": "^0.9.2"

package/skills/clickhouse-js-node-troubleshooting/reference/socket-hangup.md

@@ -109,9 +109,74 @@ const client = createClient({
 })
 ```
 
-> ⚠️ Node.js caps total received headers at ~16 KB. After ~70–80 progress headers, an exception is thrown. For a query running longer than roughly `http_headers_progress_interval_ms * 75`, this limit will be hit — use a longer interval or the fire-and-forget approach below.
+### ⚠️ Critical: 16 KB Node.js Header Size Limit
 
-**Alternatively — fire-and-forget (mutations only):** Mutations (`INSERT ... SELECT`, `OPTIMIZE`, `ALTER`) are not cancelled on the server when the client connection is lost. You can send the mutation and immediately close the connection, then poll `system.query_log` or `system.mutations` for status. See the [client repo examples](https://github.com/ClickHouse/clickhouse-js/tree/main/examples) for a concrete implementation.
+**Node.js defaults to a total received HTTP header limit of approximately 16 KB (this can be increased via the `--max-http-header-size` CLI flag[^max-header-size]).** ClickHouse sends a new progress header with each interval (~200 bytes), and after ~75 progress headers accumulate, Node.js will throw an exception and terminate the request unless that limit is raised.
+
+[^max-header-size]: Node.js also exposes a `maxHeaderSize` option on `http(s).request`, but the ClickHouse JS client currently does not forward it through `createClient`. For now, the practical workaround in clickhouse-js is to either use the `--max-http-header-size` CLI flag / `NODE_OPTIONS` (process-wide) or supply a custom `http.Agent` configured with `maxHeaderSize`. A dedicated client option is coming soon.
+
+**Maximum safe query duration formula:**
+
+```
+Max duration (seconds) ≈ http_headers_progress_interval_ms × 75 ÷ 1000
+```
+
+**Examples:**
+
+- `http_headers_progress_interval_ms: '10000'` (10s) → **~12.5 minutes** max safe duration
+- `http_headers_progress_interval_ms: '60000'` (60s) → **~75 minutes** max safe duration
+- `http_headers_progress_interval_ms: '120000'` (120s) → **~2.5 hours** max safe duration
+
+> **Note:** `http_headers_progress_interval_ms` is a `UInt64` ClickHouse setting, so it must be passed as a **string** (e.g., `'10000'`).
+
+**Raising the Node.js header limit (e.g., to 64 KB):**
+
+If you need a longer max safe duration without lengthening the progress interval, raise Node's HTTP header limit. For example, increasing it from the default 16 KB to **64 KB** quadruples the max safe duration (≈300 progress headers instead of ≈75).
+
+```bash
+# Option 1 — CLI flag when launching your app
+node --max-http-header-size=65536 app.js
+
+# Option 2 — environment variable (works with any Node entry point, including npm/ts-node)
+NODE_OPTIONS="--max-http-header-size=65536" node app.js
+```
+
+With `maxHeaderSize = 65536` (64 KB), the formula becomes:
+Max duration (seconds) ≈ http_headers_progress_interval_ms × 300 ÷ 1000
+```
+Max duration ≈ http_headers_progress_interval_ms ÷ 1000 × 300
+```
+
+Examples at 64 KB:
+
+- `http_headers_progress_interval_ms: '10000'` (10s) → **~50 minutes** max safe duration
+- `http_headers_progress_interval_ms: '60000'` (60s) → **~5 hours** max safe duration
+- `http_headers_progress_interval_ms: '120000'` (120s) → **~10 hours** max safe duration
+
+**Guidelines for choosing the interval** (subject to your load balancer's idle timeout — see trade-offs below):
+
+1. **For queries under 12 minutes:** Use `'10000'` ms (10s) intervals, if your LB idle timeout allows
+2. **For queries 12 min – 1 hour:** Use `'60000'` ms (60s) intervals, if your LB idle timeout allows
+3. **For queries 1–2 hours:** Use `'120000'` ms (120s) intervals, if your LB idle timeout allows
+4. **For mutations over 2 hours:** Use the fire-and-forget pattern (see below)
+5. **For SELECT queries over 2 hours:** Increase `http_headers_progress_interval_ms` to extend the safe duration, while keeping it below your LB idle timeout and within Node.js header-limit constraints
+
+Use this command to experiment and debug:
+
+```bash
+curl -v "http://localhost:8123/?function_sleep_max_microseconds_per_block=10000000&wait_end_of_query=1&send_progress_in_http_headers=1&max_block_size=1&query=select+sum(sleepEachRow(1))+from+numbers(10)+FORMAT+JSONEachRow"
+```
+
+Experimenting with the exact load balancer stack might be required.
+
+**Important trade-offs:**
+
+- **Shorter intervals** = better load balancer keep-alive (prevents idle timeout) but **lower max duration**
+- **Longer intervals** = higher max duration but **higher risk of LB idle timeout**
+
+As a rule of thumb, set the interval slightly **below** your load balancer's idle timeout—typically by a few seconds (for example, often around 5–20 seconds), depending on your load balancer, proxies, and network behavior—while staying under the header limit for your expected query duration.
+
+**Alternatively — fire-and-forget (mutations only):** Mutations (`INSERT ... SELECT`, `OPTIMIZE`, `ALTER`) are not cancelled on the server when the client connection is lost. You can send the mutation and immediately close the connection, then poll `system.query_log` or `system.mutations` for status. This bypasses both the load balancer idle timeout and the Node.js header limit. See the [client repo examples](https://github.com/ClickHouse/clickhouse-js/tree/main/examples) for a concrete implementation.
 
 ## Step 5 — Disable Keep-Alive entirely (last resort)