@clickhouse/client 1.20.0 → 1.21.0

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

@@ -9,12 +9,12 @@
 **Fix:** Use the `pathname` option separately:
 
 ```js
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 
 const client = createClient({
-  url: 'http://proxy:8123',
-  pathname: '/clickhouse_server', // leading slash optional; multiple segments supported
-})
+  url: "http://proxy:8123",
+  pathname: "/clickhouse_server", // leading slash optional; multiple segments supported
+});
 ```
 
 For proxies that require custom auth headers:
@@ -22,11 +22,11 @@ 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'
+import { createClient } from "@clickhouse/client";
 
 const client = createClient({
   http_headers: {
-    'My-Auth-Header': 'secret',
+    "My-Auth-Header": "secret",
   },
-})
+});
 ```

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

@@ -6,7 +6,7 @@
 
 ```js
 // What you write:
-await client.query({ query: 'SELECT 1', format: 'JSONEachRow' })
+await client.query({ query: "SELECT 1", format: "JSONEachRow" });
 
 // What the client actually sends:
 // SELECT 1
@@ -19,10 +19,10 @@ If the `query` string already contains a `FORMAT` clause, the client still appen
 
 ```js
 // ❌ Wrong — ends up as `... FORMAT CSV FORMAT JSON` → syntax error
-await client.query({ query: 'SELECT 1 FORMAT CSV' })
+await client.query({ query: "SELECT 1 FORMAT CSV" });
 
 // ✓ Correct — let the client append FORMAT via the option
-await client.query({ query: 'SELECT 1', format: 'CSV' })
+await client.query({ query: "SELECT 1", format: "CSV" });
 ```
 
 If you genuinely need to write the full SQL yourself (including the `FORMAT` clause), or you're running a statement where the appended `FORMAT` suffix is not supported, use `client.exec()` instead of `client.query()`. Use `client.insert()` for data insertion and `client.command()` for DDLs.
@@ -33,15 +33,15 @@ Some statements are not parsed by the server with a trailing `FORMAT` clause, so
 
 ```js
 // ❌ Fails — query() appends `FORMAT JSON`, which the short SHOW POLICIES syntax rejects
-await client.query({ query: 'SHOW POLICIES', format: 'JSON' })
-await client.query({ query: 'SHOW ROW POLICIES', format: 'JSON' })
+await client.query({ query: "SHOW POLICIES", format: "JSON" });
+await client.query({ query: "SHOW ROW POLICIES", format: "JSON" });
 ```
 
 **Fix:** use the full syntax `SHOW POLICIES ON *` (or `SHOW POLICIES ON db.table`), which the parser accepts together with the appended `FORMAT`:
 
 ```js
 // ✓ Works — full syntax accepts the appended FORMAT clause
-await client.query({ query: 'SHOW POLICIES ON *', format: 'JSON' })
+await client.query({ query: "SHOW POLICIES ON *", format: "JSON" });
 ```
 
 Alternatively, run the short statement through `client.exec()`, where you control the full SQL and no `FORMAT` suffix is appended.

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

@@ -6,10 +6,10 @@ Use the `{name: type}` syntax in the query string and pass values via `query_par
 
 ```js
 await client.query({
-  query: 'SELECT plus({val1: Int32}, {val2: Int32})',
-  format: 'CSV',
+  query: "SELECT plus({val1: Int32}, {val2: Int32})",
+  format: "CSV",
   query_params: { val1: 10, val2: 20 },
-})
+});
 ```
 
 ## Never use template literals for user values
@@ -18,14 +18,14 @@ When `$1`/`?` don't work, a common instinct is to interpolate values directly wi
 
 ```js
 // ❌ Dangerous — never do this with user-controlled values
-const userId = req.params.id
-await client.query({ query: `SELECT * FROM users WHERE id = ${userId}` })
+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: "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.
@@ -37,27 +37,27 @@ The ClickHouse JS client uses ClickHouse's native `{name: type}` syntax — not
 ```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: "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: "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: "SELECT * FROM t WHERE id IN {ids: Array(UInt32)}",
+  format: "JSONEachRow",
   query_params: { ids: [1, 2, 3] },
-})
+});
 ```
 
 ## Tuple parameters (`>= 1.9.0`)
@@ -65,17 +65,17 @@ await client.query({
 Use the `TupleParam` wrapper to pass a tuple:
 
 ```js
-import { TupleParam, createClient } from '@clickhouse/client'
+import { TupleParam, createClient } from "@clickhouse/client";
 
 const client = createClient({
-  url: 'http://localhost:8123',
-})
+  url: "http://localhost:8123",
+});
 
 await client.query({
-  query: 'SELECT {t: Tuple(UInt32, String)}',
-  format: 'JSONEachRow',
-  query_params: { t: new TupleParam([42, 'hello']) },
-})
+  query: "SELECT {t: Tuple(UInt32, String)}",
+  format: "JSONEachRow",
+  query_params: { t: new TupleParam([42, "hello"]) },
+});
 ```
 
 ## Map parameters (`>= 1.9.0`)
@@ -84,10 +84,10 @@ Pass a JS `Map` directly:
 
 ```js
 await client.query({
-  query: 'SELECT {m: Map(String, UInt32)}',
-  format: 'JSONEachRow',
-  query_params: { m: new Map([['key', 1]]) },
-})
+  query: "SELECT {m: Map(String, UInt32)}",
+  format: "JSONEachRow",
+  query_params: { m: new Map([["key", 1]]) },
+});
 ```
 
 ## NULL parameters
@@ -96,8 +96,8 @@ Pass `null` directly — binding fixed in `0.0.16`:
 
 ```js
 await client.query({
-  query: 'SELECT {val: Nullable(String)}',
-  format: 'JSONEachRow',
+  query: "SELECT {val: Nullable(String)}",
+  format: "JSONEachRow",
   query_params: { val: null },
-})
+});
 ```

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

@@ -9,17 +9,17 @@
 **Fix:** Remove response compression for read-only users:
 
 ```js
-import { createClient } from '@clickhouse/client'
+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: '...',
+  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

@@ -16,11 +16,11 @@
 > **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'
+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.
@@ -29,33 +29,33 @@ Look for log lines about unconsumed or dangling streams — these are a common h
 
 ```js
 // ❌ Wrong — result stream never consumed; socket is left open
-const resultSet = await client.query({ query: 'SELECT ...' })
+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()
+  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()
+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',
-})
+  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()
+const resultSet = await client.query({ query: "SELECT ..." });
+resultSet.close();
 ```
 
 ## Step 2 — Check your ESLint setup
@@ -86,7 +86,7 @@ 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.
@@ -104,9 +104,9 @@ 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
+    http_headers_progress_interval_ms: "110000", // string — UInt64 type; set ~10s below LB idle timeout
   },
-})
+});
 ```
 
 ### ⚠️ Critical: 16 KB Node.js Header Size Limit
@@ -140,9 +140,9 @@ const client = createClient({
   max_response_headers_size: 65536, // 64 KB; lifts the per-request header cap
   clickhouse_settings: {
     send_progress_in_http_headers: 1,
-    http_headers_progress_interval_ms: '110000',
+    http_headers_progress_interval_ms: "110000",
   },
-})
+});
 ```
 
 ```bash
@@ -200,5 +200,5 @@ Adds overhead (new TCP connection per request) but eliminates all Keep-Alive iss
 ```js
 const client = createClient({
   keep_alive: { enabled: false },
-})
+});
 ```

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

@@ -5,34 +5,34 @@
 ## Basic TLS (CA certificate only)
 
 ```js
-import fs from 'fs'
-import { createClient } from '@clickhouse/client'
+import fs from "fs";
+import { createClient } from "@clickhouse/client";
 
 const client = createClient({
-  url: 'https://<hostname>:<port>',
-  username: '<user>',
-  password: '<pass>',
+  url: "https://<hostname>:<port>",
+  username: "<user>",
+  password: "<pass>",
   tls: {
-    ca_cert: fs.readFileSync('certs/CA.pem'),
+    ca_cert: fs.readFileSync("certs/CA.pem"),
   },
-})
+});
 ```
 
 ## Mutual TLS (client certificate + key)
 
 ```js
-import fs from 'fs'
-import { createClient } from '@clickhouse/client'
+import fs from "fs";
+import { createClient } from "@clickhouse/client";
 
 const client = createClient({
-  url: 'https://<hostname>:<port>',
-  username: '<user>',
+  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'),
+    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`.
@@ -59,29 +59,29 @@ The server uses a self-signed cert (the certificate is its own CA). Options in o
 
    ```js
    tls: {
-     ca_cert: fs.readFileSync('certs/server.crt')
+     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'
+   import https from "https";
+   import { createClient } from "@clickhouse/client";
 
    const client = createClient({
-     url: 'https://<hostname>:<port>',
-     username: '<user>',
-     password: '<pass>',
+     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>',
+       "X-ClickHouse-User": "<user>",
+       "X-ClickHouse-Key": "<pass>",
      },
-   })
+   });
    ```
 
    > ⚠️ Never use `rejectUnauthorized: false` in production — it disables all certificate verification.