@clickhouse/client 1.18.4-head.2f6fd6b.1 → 1.18.4-head.3029a3d.1

package/README.md

@@ -105,6 +105,25 @@ See more examples in the [examples directory](./examples).
 
 See the [ClickHouse website](https://clickhouse.com/docs/integrations/javascript) for the full documentation.
 
+## AI Agent Skills
+
+This repository contains agent skills for working with the client:
+
+- `clickhouse-js-node-troubleshooting` — troubleshooting playbook for the Node.js client.
+
+Install via CLI:
+
+```sh
+# per project
+npx skills add ClickHouse/clickhouse-js
+# globally
+npx skills add ClickHouse/clickhouse-js -g
+```
+
+Or ask your agent to install it for you:
+
+> install agent skills from ClickHouse/clickhouse-js
+
 ## Usage examples
 
 We have a wide range of [examples](./examples), aiming to cover various scenarios of client usage. The overview is available in the [examples README](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/README.md#overview).

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.18.4-head.2f6fd6b.1";
+declare const _default: "1.18.4-head.3029a3d.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.2f6fd6b.1';
+exports.default = '1.18.4-head.3029a3d.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.2f6fd6b.1",
+  "version": "1.18.4-head.3029a3d.1",
   "license": "Apache-2.0",
   "keywords": [
     "clickhouse",
@@ -20,17 +20,27 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
+  "agents": {
+    "skills": [
+      {
+        "name": "clickhouse-js-node-troubleshooting",
+        "path": "./skills/clickhouse-js-node-troubleshooting"
+      }
+    ]
+  },
   "scripts": {
-    "prepack": "cp ../../README.md ../../LICENSE .",
+    "pack": "npm pack",
+    "prepack": "rm -rf skills && cp ../../README.md ../../LICENSE . && cp -r ../../skills .",
     "typecheck": "tsc --noEmit",
     "lint": "eslint --max-warnings=0 .",
     "lint:fix": "eslint . --fix",
     "build": "rm -rf dist; tsc"
   },
   "dependencies": {
-    "@clickhouse/client-common": "1.18.4-head.2f6fd6b.1"
+    "@clickhouse/client-common": "1.18.4-head.3029a3d.1"
   },
   "devDependencies": {
     "simdjson": "^0.9.2"

package/skills/clickhouse-js-node-troubleshooting/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: clickhouse-js-node-troubleshooting
+description: >
+  Troubleshoot and resolve common issues with the ClickHouse Node.js client
+  (@clickhouse/client). Use this skill whenever a user reports errors, unexpected
+  behavior, or configuration questions involving the Node.js client specifically —
+  including socket hang-up errors, Keep-Alive problems, stream handling issues, data
+  type mismatches, read-only user restrictions, proxy/TLS setup problems, or long-running
+  query timeouts. Trigger even when the user hasn't precisely named the issue; vague
+  symptoms like "my inserts keep failing" or "connection drops randomly" in a Node.js
+  context are strong signals to use this skill. Do NOT use for browser/Web client issues.
+---
+
+# ClickHouse Node.js Client Troubleshooting
+
+Reference: https://clickhouse.com/docs/integrations/javascript
+
+> **⚠️ Node.js runtime only.** This skill covers the `@clickhouse/client` package running in a **Node.js runtime** exclusively — including **Next.js Node runtime** API routes, React Server Components, Server Actions, and standard Node.js processes. Do **not** apply this skill to browser client components, Web Workers, **Next.js Edge runtime**, Cloudflare Workers, or any usage of `@clickhouse/client-web`. For browser/edge environments, the correct package is `@clickhouse/client-web`.
+
+---
+
+## How to Use This Skill
+
+1. **Identify the issue** — match symptoms to the Issue Index below and read the corresponding reference file.
+2. **Lead with the diagnosis** — explain what's likely causing the issue before giving the fix.
+3. **Note version constraints** — flag if a fix requires a minimum client version and check it against what the user provided.
+4. **Ask only what's missing** — if the fix is version-dependent and you don't know their version, ask; otherwise help immediately.
+
+---
+
+## Issue Index
+
+Identify the user's issue from the list below and read the corresponding reference file for detailed troubleshooting steps.
+
+| Issue                                 | Symptoms                                                                                       | Reference file                |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------- |
+| **Socket Hang-Up / ECONNRESET**       | `socket hang up`, `ECONNRESET`, intermittent connection drops, long-running queries timing out | `reference/socket-hangup.md`  |
+| **Data Type Mismatches**              | Large integers returned as strings, decimal precision loss, Date/DateTime insertion failures   | `reference/data-types.md`     |
+| **Read-Only User Errors**             | Errors when using response compression with `readonly=1` users                                 | `reference/readonly-users.md` |
+| **Proxy / Pathname URL Confusion**    | Wrong database selected, requests failing behind a proxy with a path prefix                    | `reference/proxy-pathname.md` |
+| **TLS / Certificate Errors**          | TLS handshake failures, certificate verification issues, mutual TLS setup                      | `reference/tls.md`            |
+| **Compression Not Working**           | GZIP compression not activating for requests or responses                                      | `reference/compression.md`    |
+| **Logging Not Showing Anything**      | No log output, need custom logger integration                                                  | `reference/logging.md`        |
+| **Query Parameters Not Interpolated** | Parameterized queries not working, SQL injection concerns                                      | `reference/query-params.md`   |
+
+---
+
+## Still Stuck?
+
+- [JS client source + full examples](https://github.com/ClickHouse/clickhouse-js/tree/main/examples)
+- [ClickHouse JS client docs](https://clickhouse.com/docs/integrations/javascript)
+- [ClickHouse supported formats](https://clickhouse.com/docs/interfaces/formats)

package/skills/clickhouse-js-node-troubleshooting/evals/evals.json

@@ -0,0 +1,126 @@
+{
+  "skill_name": "clickhouse-js-node-troubleshooting",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "I'm using @clickhouse/client in a Node.js API server and I get `socket hang up` errors, but only after the server has been idle for a while — if I hammer it with requests it's fine. Any idea what's going on? I'm on version 0.3.2.",
+      "expected_output": "Explanation that this is a Keep-Alive idle socket timeout mismatch. The server's keep-alive timeout is shorter than the client's idle_socket_ttl. Should recommend checking the server's keep-alive timeout with curl and setting idle_socket_ttl to ~500ms below it.",
+      "files": [],
+      "expectations": [
+        "Identifies the likely cause as a Keep-Alive idle timeout mismatch rather than a generic network problem.",
+        "Recommends checking the server or proxy Keep-Alive timeout, including the curl-based header check or equivalent.",
+        "Explains that idle_socket_ttl should be set slightly below the server timeout, around 500ms lower."
+      ]
+    },
+    {
+      "id": 1,
+      "prompt": "I keep getting ECONNRESET on literally every second request in my Node.js app. Here's my code:\n\n```js\nconst resultSet = await client.query({ query: 'SELECT count() FROM events' })\nconst stream = resultSet.stream()\n// then I do some stuff and run another query\nconst result2 = await client.query({ query: 'SELECT 1' })\n```\n\nThe first query always works, second always fails. What am I doing wrong?",
+      "expected_output": "Diagnosis of dangling stream — the stream from the first query is never fully iterated or closed, corrupting the Keep-Alive socket. Fix: either fully consume via for-await or call resultSet.close().",
+      "files": [],
+      "expectations": [
+        "Diagnoses the problem as an unconsumed or dangling ResultSet stream causing the next request to fail.",
+        "Explains that the first query response must be fully consumed or explicitly closed before reusing the client connection.",
+        "Provides at least one concrete fix using full stream consumption, resultSet.json/text, or resultSet.close()."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "My UInt64 column values are coming back as strings in JavaScript — like `\"9007199254740993\"` instead of a number. I'm using JSONEachRow format. Is there a way to get them as actual numbers?",
+      "expected_output": "Explanation that ClickHouse serializes 64-bit integers as strings in JSON formats to prevent overflow. Option 1: use output_format_json_quote_64bit_integers: 0 (with precision-loss warning). Option 2: use BigInt or a BigInt-safe JSON parser. Should mention the precision risk.",
+      "files": [],
+      "expectations": [
+        "Explains that 64-bit integers are returned as strings in JSON formats to avoid JavaScript precision issues.",
+        "Mentions output_format_json_quote_64bit_integers: 0 as a way to receive numeric JSON output.",
+        "Warns that converting these values to Number can lose precision and suggests a safer BigInt-oriented alternative."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We have ClickHouse sitting behind an nginx reverse proxy. The proxy URL is http://myproxy.internal:8123/clickhouse. I'm on @clickhouse/client 1.3.0 and creating the client like this:\n\n```js\nconst client = createClient({ url: 'http://myproxy.internal:8123/clickhouse' })\n```\n\nBut it seems to be selecting the wrong database — it's trying to use 'clickhouse' as the database name instead of going through the proxy path. What am I missing?",
+      "expected_output": "Explanation of the proxy/pathname confusion: the path in the URL is being interpreted as the database name. Fix: use the `pathname` option separately — createClient({ url: 'http://myproxy.internal:8123', pathname: '/clickhouse' }). Should note this requires >= 1.0.0.",
+      "files": [],
+      "expectations": [
+        "Explains that putting the path segment in url makes the client interpret it as the database name or otherwise mishandle the proxy path.",
+        "Shows the fix using a base url plus a separate pathname option.",
+        "Acknowledges the version dependency by either noting pathname requires >= 1.0.0 or asking for the client version before assuming that fix is available."
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "I'm getting this error when connecting to our self-hosted ClickHouse over HTTPS:\n\n```\nError: unable to verify the first certificate\n    at TLSSocket.onConnectEnd (_tls_wrap.js:1495:19)\n```\n\nWe use an internal certificate authority. I'm using @clickhouse/client 1.3.0 with Node.js 18. How do I fix this?",
+      "expected_output": "Diagnosis: private/internal CA not trusted by Node.js. Fix: pass the CA certificate via the tls.ca_cert option using fs.readFileSync. Should show the createClient({ url: 'https://...', tls: { ca_cert: fs.readFileSync('certs/CA.pem') } }) example.",
+      "files": [],
+      "expectations": [
+        "Diagnoses the error as Node.js not trusting the internal or private certificate authority.",
+        "Shows how to pass the CA certificate via tls.ca_cert with fs.readFileSync or an equivalent code example.",
+        "Avoids recommending insecure production advice such as disabling certificate verification without clearly marking it as development-only."
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "My parameterized queries aren't working. I'm doing:\n\n```js\nawait client.query({\n  query: 'SELECT * FROM users WHERE id = $1 AND status = $2',\n  query_params: { 1: 42, 2: 'active' }\n})\n```\n\nThe values just don't get substituted. Coming from PostgreSQL and this was how params work there.",
+      "expected_output": "Explanation that ClickHouse JS client uses ClickHouse's native {name: type} syntax, not $1/$2 placeholders. Show the correct syntax: { query: 'SELECT * FROM users WHERE id = {id: UInt32} AND status = {status: String}', query_params: { id: 42, status: 'active' } }. Warn against template literal interpolation (SQL injection risk).",
+      "files": [],
+      "expectations": [
+        "Explains that the ClickHouse JS client does not use PostgreSQL-style $1 or $2 placeholders.",
+        "Provides a corrected example using ClickHouse's native {name: type} parameter syntax with query_params keys matching the names.",
+        "Warns against interpolating user values directly into the SQL string because of SQL injection risk."
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "I enabled response compression in @clickhouse/client for my readonly user, but I'm getting an error from ClickHouse that says something like 'Cannot modify setting enable_http_compression for user with readonly=1'. My client setup:\n\n```js\nconst client = createClient({\n  username: 'readonly_user',\n  password: 'secret',\n  compression: { response: true }\n})\n```",
+      "expected_output": "Explanation that readonly=1 users cannot change the enable_http_compression setting, which response compression requires. Fix: remove compression.response: true (or set to false). Note that request compression is unaffected. Mention that in >= 1.0.0, response compression is disabled by default.",
+      "files": [],
+      "expectations": [
+        "Explains that response compression toggles enable_http_compression, which a readonly=1 user cannot modify.",
+        "Recommends removing or disabling compression.response for this user.",
+        "Notes that request compression is a separate setting and is not blocked by the readonly restriction."
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "I'm on @clickhouse/client 1.3.0 and trying to set up structured logging to pipe into our observability stack (we use pino). I want to forward all client log messages at INFO level and above to pino. How do I wire that up?",
+      "expected_output": "Should show how to implement the Logger interface with a class (MyLogger implements Logger) that forwards to pino, then pass it via createClient({ log: { LoggerClass: MyLogger, level: ClickHouseLogLevel.INFO } }). Should show the debug/info/warn/error/trace method signatures.",
+      "files": [],
+      "expectations": [
+        "Shows a custom Logger implementation or equivalent logger wiring that forwards client logs to pino.",
+        "Configures createClient with log.LoggerClass and ClickHouseLogLevel.INFO or an equivalent INFO-level setup.",
+        "Acknowledges the version dependency by either noting this logging API requires >= 0.2.0 or asking for the client version before assuming availability."
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "I'm using `@clickhouse/client-web` inside a Next.js Edge route and trying to debug random request failures and TLS weirdness. Can you walk me through the Node.js client socket and certificate options I should tune?",
+      "expected_output": "Should explicitly reject applying the Node.js troubleshooting flow because this is an Edge/browser-style runtime using `@clickhouse/client-web`, not `@clickhouse/client`. Must redirect the user to the web client / runtime-appropriate guidance instead of suggesting Node-only socket, keep-alive, or tls options.",
+      "files": [],
+      "expectations": [
+        "Explicitly states that this skill's Node.js guidance does not apply to @clickhouse/client-web in a Next.js Edge runtime.",
+        "Avoids recommending Node-only configuration such as keep_alive, socket TTL tuning, custom HTTP agents, or tls.ca_cert for this case.",
+        "Redirects the user toward runtime-appropriate web or edge guidance instead of continuing with Node client troubleshooting."
+      ]
+    },
+    {
+      "id": 9,
+      "prompt": "I'm on @clickhouse/client 1.6.0 talking to a self-hosted ClickHouse cluster over HTTP. I turned on `compression: { response: true }` but the responses still don't look compressed. This is not a readonly user, and there is no settings error from ClickHouse. What should I check?",
+      "expected_output": "Should explain that in >= 1.0.0 response compression is disabled by default unless enabled, but since it is already enabled here the next checks are whether the server has HTTP compression enabled and whether the user is confusing request compression with response compression. Should mention that only GZIP is supported and that request compression does not affect response bodies.",
+      "files": [],
+      "expectations": [
+        "Recognizes that this is not the readonly-user failure mode because there is no settings error and the user already enabled response compression.",
+        "Recommends checking whether the ClickHouse server has HTTP compression enabled.",
+        "Clarifies that request compression and response compression are separate, and that only GZIP is supported."
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "We run a long `INSERT INTO dst SELECT * FROM src` through @clickhouse/client in a Node.js worker. It can sit there for a couple minutes with no rows coming back, and then our AWS load balancer drops the connection around the 120 second mark. Smaller queries are fine. We're on client 1.4.0. How should we handle this?",
+      "expected_output": "Should diagnose this as a long-running query idle-timeout problem rather than a dangling stream issue. Must recommend increasing request_timeout and enabling periodic progress headers with send_progress_in_http_headers and http_headers_progress_interval_ms set below the load balancer idle timeout. Should also mention the Node.js response-header limit tradeoff for very long queries and optionally suggest the fire-and-forget mutation pattern.",
+      "files": [],
+      "expectations": [
+        "Diagnoses the issue as a long-running idle timeout at the load balancer rather than a dangling stream or ordinary per-request ECONNRESET problem.",
+        "Recommends increasing request_timeout and enabling send_progress_in_http_headers with http_headers_progress_interval_ms below the load balancer timeout.",
+        "Mentions the Node.js received-header limit tradeoff for very long-running progress-header use or offers the fire-and-forget mutation pattern as an alternative."
+      ]
+    }
+  ]
+}

package/skills/clickhouse-js-node-troubleshooting/reference/compression.md

@@ -0,0 +1,27 @@
+# Compression Not Working
+
+> **Applies to:** all versions. Response compression was enabled by default in `< 1.0.0` and **disabled by default since `>= 1.0.0`** — you must explicitly enable it. Request compression has always been opt-in.
+
+Both request and response compression are supported. Only **GZIP** is supported (via zlib).
+
+```js
+import { createClient } from '@clickhouse/client'
+const client = createClient({
+  compression: {
+    response: true,
+    request: true,
+  },
+})
+```
+
+## Compression enabled but getting an error?
+
+If you enable `compression.response: true` and get a ClickHouse settings error, you are likely connecting as a `readonly=1` user. Response compression requires the `enable_http_compression` setting, which read-only users cannot change.
+
+See [`reference/readonly-users.md`](./readonly-users.md) for the fix.
+
+## Compression enabled but response doesn't seem compressed?
+
+- Verify your version-specific defaults — response compression was enabled by default in `< 1.0.0` and is **disabled by default** in `>= 1.0.0`, so on newer versions you must enable `compression.response: true` explicitly.
+- Check that the ClickHouse server has HTTP compression enabled (`enable_http_compression = 1` in server config). By default this is enabled on ClickHouse Cloud and most self-hosted setups.
+- Request compression (`compression.request: true`) compresses the request body sent to ClickHouse. It has no effect on the response.

package/skills/clickhouse-js-node-troubleshooting/reference/data-types.md

@@ -0,0 +1,73 @@
+# Data Type Mismatches
+
+## Large integers returned as strings
+
+> **Applies to:** all versions. The `output_format_json_quote_64bit_integers` ClickHouse setting is server-side and can be passed via `clickhouse_settings` in any client version.
+
+`UInt64`, `Int64`, `UInt128`, `Int128`, `UInt256`, `Int256` are serialized as **strings** in `JSON*` formats to prevent overflow (they exceed `Number.MAX_SAFE_INTEGER`).
+
+To receive them as numbers (use with caution — precision loss possible):
+
+```js
+const resultSet = await client.query({
+  query: 'SELECT toUInt64(9007199254740993)',
+  format: 'JSONEachRow',
+  clickhouse_settings: { output_format_json_quote_64bit_integers: 0 },
+})
+```
+
+> **Tip (`>= 1.15.0`):** BigInt values are now supported in query parameters, so you can safely pass large integers as bind params without string workarounds.
+
+## Decimals losing precision on read
+
+> **Applies to:** all versions (this is a ClickHouse JSON serialization behavior). For custom JSON parse/stringify (e.g., using a BigInt-safe parser), see `>= 1.14.0` which added configurable `json.parse` and `json.stringify` functions.
+
+ClickHouse returns Decimals as numbers by default in `JSON*` formats. Cast to string in the query:
+
+```js
+const resultSet = await client.query({
+  query: `
+    SELECT toString(my_decimal) AS my_decimal
+    FROM my_table
+  `,
+  format: 'JSONEachRow',
+})
+```
+
+When inserting, always use the string representation to avoid precision loss:
+
+```js
+await client.insert({
+  table: 'my_table',
+  values: [{ dec64: '123456789123456.789' }],
+  format: 'JSONEachRow',
+})
+```
+
+## Format Selection Quick Reference
+
+| Use case                    | Recommended format                  | Min version                           |
+| --------------------------- | ----------------------------------- | ------------------------------------- |
+| Insert/select JS objects    | `JSONEachRow`                       | all                                   |
+| Bulk insert arrays          | `JSONEachRow`                       | all                                   |
+| Stream large result sets    | `JSONEachRow`, `JSONCompactEachRow` | all                                   |
+| CSV file streaming          | `CSV`, `CSVWithNames`               | all                                   |
+| Parquet file streaming      | `Parquet`                           | `>= 0.2.6`                            |
+| Single JSON object response | `JSON`, `JSONCompact`               | `JSON` all; `JSONCompact` `>= 0.0.14` |
+| Stream with progress        | `JSONEachRowWithProgress`           | `>= 1.7.0`                            |
+
+> ⚠️ `JSON` and `JSONCompact` return a single object and **cannot be streamed**.
+
+## Date/DateTime insertion fails or produces wrong values
+
+> **Applies to:** all versions. Note that `>= 0.2.1` changed Date object serialization to use time-zone-agnostic Unix timestamps instead of timezone-naive datetime strings, which fixed timezone mismatch issues between client and server.
+
+- `Date` / `Date32` columns accept **strings only** (e.g., `'2024-01-15'`).
+- `DateTime` / `DateTime64` columns accept strings **or** JS `Date` objects. To use `Date` objects, set:
+
+```js
+import { createClient } from '@clickhouse/client'
+const client = createClient({
+  clickhouse_settings: { date_time_input_format: 'best_effort' },
+})
+```

package/skills/clickhouse-js-node-troubleshooting/reference/logging.md

@@ -0,0 +1,44 @@
+# Logging Not Showing Anything
+
+> **Requires:** `>= 0.2.0` (explicit `log.level` config option introduced in 0.2.0, replacing the `CLICKHOUSE_LOG_LEVEL` env var from 0.0.11). Custom `LoggerClass` also available since `>= 0.2.0`. In `>= 1.18.1`, the default changed from `OFF` to `WARN` and logging became lazy (messages only constructed if the log level matches). In `>= 1.18.1`, structured context fields (`connection_id`, `query_id`, `request_id`, `socket_id`) are available in logger `args`.
+
+The default log level is **OFF** (for `< 1.18.1`) or **WARN** (for `>= 1.18.1`). Enable it explicitly:
+
+```js
+import { ClickHouseLogLevel, createClient } from '@clickhouse/client'
+
+const client = createClient({
+  log: {
+    level: ClickHouseLogLevel.DEBUG, // TRACE | DEBUG | INFO | WARN | ERROR
+  },
+})
+```
+
+To use a custom logger (e.g., to pipe to your observability stack), implement the `Logger` interface:
+
+```ts
+import { ClickHouseLogLevel, createClient } from '@clickhouse/client'
+import type { Logger } from '@clickhouse/client'
+
+class MyLogger implements Logger {
+  debug({ module, message, args }) {
+    /* ... */
+  }
+  info({ module, message, args }) {
+    /* ... */
+  }
+  warn({ module, message, args, err }) {
+    /* ... */
+  }
+  error({ module, message, args, err }) {
+    /* ... */
+  }
+  trace({ module, message, args }) {
+    /* ... */
+  }
+}
+
+const client = createClient({
+  log: { LoggerClass: MyLogger, level: ClickHouseLogLevel.INFO },
+})
+```

package/skills/clickhouse-js-node-troubleshooting/reference/proxy-pathname.md

@@ -0,0 +1,32 @@
+# Proxy / Pathname URL Confusion
+
+> **Requires:** `>= 1.0.0` (the `pathname` config option and URL-based configuration were introduced in 1.0.0). For `< 1.0.0`, a partial fix for pathname handling in the `host` parameter was shipped in `0.2.5`.
+
+**Symptom:** Wrong database is selected, or requests fail when ClickHouse is behind a proxy with a path prefix (e.g., `http://proxy:8123/clickhouse_server`).
+
+**Cause:** Passing the pathname in `url` makes the client treat it as the database name.
+
+**Fix:** Use the `pathname` option separately:
+
+```js
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: 'http://proxy:8123',
+  pathname: '/clickhouse_server', // leading slash optional; multiple segments supported
+})
+```
+
+For proxies that require custom auth headers:
+
+> **Requires:** `>= 1.0.0` (`http_headers` config option; replaces the deprecated `additional_headers` from `>= 0.2.9`). Per-request `http_headers` overrides are available since `>= 1.11.0`.
+
+```js
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  http_headers: {
+    'My-Auth-Header': 'secret',
+  },
+})
+```

package/skills/clickhouse-js-node-troubleshooting/reference/query-params.md

@@ -0,0 +1,103 @@
+# Query Parameters Not Interpolated
+
+> **Applies to:** all versions. NULL parameter binding was fixed in `0.0.16`. Tuple support via `TupleParam` wrapper and JS `Map` as a query parameter were added in `>= 1.9.0`. BigInt values in query parameters are supported since `>= 1.15.0`. Boolean formatting in `Array`/`Tuple`/`Map` params was fixed in `>= 1.13.0`.
+
+Use the `{name: type}` syntax in the query string and pass values via `query_params`:
+
+```js
+await client.query({
+  query: 'SELECT plus({val1: Int32}, {val2: Int32})',
+  format: 'CSV',
+  query_params: { val1: 10, val2: 20 },
+})
+```
+
+## Never use template literals for user values
+
+When `$1`/`?` don't work, a common instinct is to interpolate values directly with a template literal. Don't — this bypasses ClickHouse's server-side escaping and opens the door to SQL injection:
+
+```js
+// ❌ Dangerous — never do this with user-controlled values
+const userId = req.params.id
+await client.query({ query: `SELECT * FROM users WHERE id = ${userId}` })
+
+// ✓ Safe — parameterized
+await client.query({
+  query: 'SELECT * FROM users WHERE id = {id: UInt32}',
+  query_params: { id: userId },
+})
+```
+
+Always bring this up when answering query-params questions, especially when the user is coming from another database (PostgreSQL, MySQL, etc.) — they're the most likely to reach for template literals as a fallback.
+
+## Common mistake: wrong parameter syntax
+
+The ClickHouse JS client uses ClickHouse's native `{name: type}` syntax — not `$1`/`?`/`:name` placeholders from other databases:
+
+```js
+// ❌ Wrong — these don't work
+await client.query({
+  query: 'SELECT * FROM t WHERE id = $1',
+  query: 'SELECT * FROM t WHERE id = ?',
+  query: 'SELECT * FROM t WHERE id = :id',
+  query_params: { id: 42 },
+})
+
+// ✓ Correct
+await client.query({
+  query: 'SELECT * FROM t WHERE id = {id: UInt32}',
+  query_params: { id: 42 },
+})
+```
+
+## Array parameters
+
+```js
+await client.query({
+  query: 'SELECT * FROM t WHERE id IN {ids: Array(UInt32)}',
+  format: 'JSONEachRow',
+  query_params: { ids: [1, 2, 3] },
+})
+```
+
+## Tuple parameters (`>= 1.9.0`)
+
+Use the `TupleParam` wrapper to pass a tuple:
+
+```js
+import { TupleParam, createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: 'http://localhost:8123',
+})
+
+await client.query({
+  query: 'SELECT {t: Tuple(UInt32, String)}',
+  format: 'JSONEachRow',
+  query_params: { t: new TupleParam([42, 'hello']) },
+})
+```
+
+## Map parameters (`>= 1.9.0`)
+
+Pass a JS `Map` directly:
+
+```js
+await client.query({
+  query: 'SELECT {m: Map(String, UInt32)}',
+  format: 'JSONEachRow',
+  query_params: { m: new Map([['key', 1]]) },
+})
+```
+
+## NULL parameters
+
+Pass `null` directly — binding fixed in `0.0.16`:
+
+```js
+await client.query({
+  query: 'SELECT {val: Nullable(String)}',
+  format: 'JSONEachRow',
+  query_params: { val: null },
+})
+```

package/skills/clickhouse-js-node-troubleshooting/reference/readonly-users.md

@@ -0,0 +1,25 @@
+# Read-Only User Errors
+
+> **Applies to:** all versions. In `>= 1.0.0`, `compression.response` was changed to **disabled by default** specifically to avoid this confusing error for read-only users. If you are on `< 1.0.0`, response compression was enabled by default and you must explicitly disable it.
+
+**Symptom:** Error when using `compression: { response: true }` with a `readonly=1` user.
+
+**Cause:** Response compression requires the `enable_http_compression` setting, which `readonly=1` users cannot change. Note: **request compression** (`compression: { request: true }`) is unaffected by this restriction — only response compression triggers the error.
+
+**Fix:** Remove response compression for read-only users:
+
+```js
+import { createClient } from '@clickhouse/client'
+
+// Don't do this with a readonly=1 user:
+// compression: { response: true }
+
+const client = createClient({
+  username: 'my_readonly_user',
+  password: '...',
+  // compression omitted, or explicitly set to false
+  compression: {
+    response: false,
+  },
+})
+```

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

@@ -0,0 +1,191 @@
+# Socket Hang-Up / ECONNRESET
+
+**Symptom:** `socket hang up` or `ECONNRESET` errors, often intermittent.
+
+**Root cause:** The server or load balancer closes the Keep-Alive connection before the client detects it and stops reusing the socket.
+
+**Quick triage:**
+
+- Errors on every request → likely dangling stream (Step 1–2)
+- Errors only after idle periods → Keep-Alive timeout mismatch (Step 3)
+- Errors on long-running queries (INSERT FROM SELECT, etc.) → load balancer idle timeout (Step 4)
+- Can't diagnose → disable Keep-Alive as a last resort (Step 5)
+
+## Step 1 — Enable WARN-level logging to find dangling streams
+
+> **Requires:** `>= 0.2.0` (logging support with `log.level` config option). In `>= 1.18.1`, the default log level changed from `OFF` to `WARN`, so this step may already be active. In `>= 1.18.2`, the client auto-emits a WARN log with Keep-Alive troubleshooting hints when an `ECONNRESET` is detected. In `>= 1.12.0`, a warning is logged when a socket is closed without fully consuming the stream.
+
+```js
+import { createClient, ClickHouseLogLevel } from '@clickhouse/client'
+
+const client = createClient({
+  log: { level: ClickHouseLogLevel.WARN },
+})
+```
+
+Look for log lines about unconsumed or dangling streams — these are a common hidden cause. A **dangling stream** is a query response stream that was never fully consumed or explicitly closed with `ResultSet.close()`. Because the Node.js client reuses sockets (Keep-Alive), leaving a stream open corrupts the socket and causes the _next_ request to fail with `ECONNRESET`. Errors on **every request** strongly suggest dangling streams rather than a Keep-Alive timeout mismatch.
+
+**Common dangling stream patterns:**
+
+```js
+// ❌ Wrong — result stream never consumed; socket is left open
+const resultSet = await client.query({ query: 'SELECT ...' })
+// result is abandoned without calling .json(), .text(), .stream(), or .close()
+
+// ❌ Wrong — stream created but not fully piped/iterated
+const resultSet = await client.query({
+  query: 'SELECT ...',
+  format: 'JSONEachRow',
+})
+const stream = resultSet.stream()
+// stream is never iterated and resultSet is never closed
+
+// ✓ Correct — consume via .json()
+const resultSet = await client.query({ query: 'SELECT ...' })
+const data = await resultSet.json()
+
+// ✓ Correct — consume via async iteration
+const resultSet = await client.query({
+  query: 'SELECT ...',
+  format: 'JSONEachRow',
+})
+for await (const rows of resultSet.stream()) {
+  // process rows
+}
+
+// ✓ Correct — explicitly close; this destroys the underlying socket immediately
+const resultSet = await client.query({ query: 'SELECT ...' })
+resultSet.close()
+```
+
+## Step 2 — Check your ESLint setup
+
+Add the [`no-floating-promises`](https://typescript-eslint.io/rules/no-floating-promises/) ESLint rule. Unhandled promises leave streams dangling, which can cause the server to close the socket.
+
+Even with `await`, if the returned `ResultSet` is not consumed (no `.json()`, `.text()`, `.close()`, or full stream iteration), the socket is left open. The ESLint rule catches the promise case; code review is needed for the "awaited but unconsumed result" case.
+
+## Step 3 — Find the server's Keep-Alive timeout
+
+```bash
+curl -v --data-binary "SELECT 1" <your_clickhouse_url>
+```
+
+Check the response headers:
+
+```
+< Connection: Keep-Alive
+< Keep-Alive: timeout=10
+```
+
+> **Requires:** `>= 0.3.0` (`keep_alive.idle_socket_ttl` was introduced in 0.3.0 with a default of 2500 ms, replacing the older `keep_alive.socket_ttl` from 0.1.1 which was removed in 0.3.0).
+
+The default `idle_socket_ttl` in the client is **2500 ms**, which is safe for servers with a 3 s timeout (common in ClickHouse < 23.11). If your server has a higher timeout (e.g., 10 s), you can safely increase:
+
+```js
+const client = createClient({
+  keep_alive: {
+    idle_socket_ttl: 9000, // stay ~500ms below the server's timeout
+  },
+})
+```
+
+> ⚠️ If you still get errors after increasing, **lower** the value, not raise it.
+
+> **Tip (`>= 1.18.3`):** Enable `keep_alive.eagerly_destroy_stale_sockets: true` to proactively destroy sockets that have been idle longer than `idle_socket_ttl` before each request. This helps when event loop delays prevent the idle timeout callback from firing on time.
+
+## Step 4 — Long-running queries with no data in/out (INSERT FROM SELECT, etc.)
+
+> **Requires:** `>= 1.0.0` (`request_timeout` default was fixed to 30 000 ms in 0.3.0; `url`-based configuration including `request_timeout` via URL params available since 1.0.0).
+
+Load balancers may close idle connections mid-query. Force periodic progress headers:
+
+```js
+const client = createClient({
+  request_timeout: 400_000, // e.g. 400s for long queries
+  clickhouse_settings: {
+    send_progress_in_http_headers: 1,
+    http_headers_progress_interval_ms: '110000', // string — UInt64 type; set ~10s below LB idle timeout
+  },
+})
+```
+
+### ⚠️ Critical: 16 KB Node.js Header Size Limit
+
+**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)
+
+> **Requires:** `>= 0.1.1` (Keep-Alive disable option introduced in 0.1.1).
+
+Adds overhead (new TCP connection per request) but eliminates all Keep-Alive issues:
+
+```js
+const client = createClient({
+  keep_alive: { enabled: false },
+})
+```

package/skills/clickhouse-js-node-troubleshooting/reference/tls.md

@@ -0,0 +1,91 @@
+# TLS / Certificate Errors
+
+> **Requires:** `>= 0.0.8` (basic and mutual TLS support added in 0.0.8). For custom HTTP agent with TLS, see `>= 1.2.0` (`http_agent` option); note that when using a custom agent, the `tls` config option is ignored.
+
+## Basic TLS (CA certificate only)
+
+```js
+import fs from 'fs'
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: 'https://<hostname>:<port>',
+  username: '<user>',
+  password: '<pass>',
+  tls: {
+    ca_cert: fs.readFileSync('certs/CA.pem'),
+  },
+})
+```
+
+## Mutual TLS (client certificate + key)
+
+```js
+import fs from 'fs'
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: 'https://<hostname>:<port>',
+  username: '<user>',
+  tls: {
+    ca_cert: fs.readFileSync('certs/CA.pem'),
+    cert: fs.readFileSync('certs/client.crt'),
+    key: fs.readFileSync('certs/client.key'),
+  },
+})
+```
+
+> **Tip (`>= 1.2.0`):** If you need a custom HTTP(S) agent, use the `http_agent` option. Only set `set_basic_auth_header: false` if you must avoid sending the basic-auth `Authorization` header (for example, due to a header conflict); in that case, provide alternative auth headers such as `X-ClickHouse-User` / `X-ClickHouse-Key` via `http_headers`.
+
+## Common TLS errors
+
+### `UNABLE_TO_VERIFY_LEAF_SIGNATURE` / `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`
+
+**Scenario A — Private/internal CA (most common for self-hosted):** The server's certificate was issued by a private CA that Node.js doesn't trust. Pass the CA certificate explicitly:
+
+```js
+tls: {
+  ca_cert: fs.readFileSync('certs/CA.pem'),
+}
+```
+
+**Scenario B — ClickHouse Cloud:** The CA is a well-known public CA; this error typically means the system CA bundle is outdated or the URL/hostname is wrong. Updating Node.js or the system certificates usually resolves it.
+
+### `self signed certificate` / `self signed certificate in certificate chain`
+
+The server uses a self-signed cert (the certificate is its own CA). Options in order of preference:
+
+1. Pass the self-signed cert as the CA:
+
+   ```js
+   tls: {
+     ca_cert: fs.readFileSync('certs/server.crt')
+   }
+   ```
+
+2. For development only — disable verification via a custom agent (`>= 1.2.0`):
+
+   ```js
+   import https from 'https'
+   import { createClient } from '@clickhouse/client'
+
+   const client = createClient({
+     url: 'https://<hostname>:<port>',
+     username: '<user>',
+     password: '<pass>',
+     http_agent: new https.Agent({ rejectUnauthorized: false }),
+     // Optional: only disable the basic-auth Authorization header if you need to
+     // provide alternative auth headers instead.
+     set_basic_auth_header: false,
+     http_headers: {
+       'X-ClickHouse-User': '<user>',
+       'X-ClickHouse-Key': '<pass>',
+     },
+   })
+   ```
+
+   > ⚠️ Never use `rejectUnauthorized: false` in production — it disables all certificate verification.
+
+### `ERR_SSL_WRONG_VERSION_NUMBER` / `ECONNREFUSED` on HTTPS URL
+
+The client is connecting with HTTPS but the server is listening on plain HTTP. Change the URL scheme to `http://` or enable TLS on the ClickHouse server.