@clickhouse/client 1.20.0 → 1.21.0-head.68dd619.1

package/skills/clickhouse-js-node-coding/reference/insert-values.md

@@ -14,7 +14,7 @@ await client.command({
     INSERT INTO target
     SELECT * FROM source
   `,
-})
+});
 ```
 
 Use `command()` (not `insert()`) — there is no row payload to send.
@@ -38,13 +38,13 @@ await client.command({
     )
   `,
   query_params: {
-    id: '00112233445566778899aabbccddeeff',
-    timestamp: '2026-05-06 12:34:56',
-    email: 'alice@example.com',
-    name: 'Alice',
+    id: "00112233445566778899aabbccddeeff",
+    timestamp: "2026-05-06 12:34:56",
+    email: "alice@example.com",
+    name: "Alice",
   },
   clickhouse_settings: { wait_end_of_query: 1 },
-})
+});
 ```
 
 Do not build `VALUES` rows with string interpolation or manual escaping. If
@@ -61,13 +61,13 @@ session-wide.
 
 ```ts
 await client.insert({
-  table: 'events',
-  format: 'JSONEachRow',
-  values: [{ id: '42', dt: new Date() }],
+  table: "events",
+  format: "JSONEachRow",
+  values: [{ id: "42", dt: new Date() }],
   clickhouse_settings: {
-    date_time_input_format: 'best_effort', // default on the Cloud
+    date_time_input_format: "best_effort", // default on the Cloud
   },
-})
+});
 ```
 
 > JS `Date` objects do **not** work for the `Date` type (date-only) — pass
@@ -97,22 +97,22 @@ await client.command({
     )
     ENGINE MergeTree ORDER BY id
   `,
-})
+});
 
 await client.insert({
-  table: 'prices',
-  format: 'JSONEachRow',
+  table: "prices",
+  format: "JSONEachRow",
   values: [
     {
       id: 1,
-      dec32: '1234567.89',
-      dec64: '123456789123456.789',
-      dec128: '1234567891234567891234567891.1234567891',
+      dec32: "1234567.89",
+      dec64: "123456789123456.789",
+      dec128: "1234567891234567891234567891.1234567891",
       dec256:
-        '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
+        "12345678912345678912345678911234567891234567891234567891.12345678911234567891",
     },
   ],
-})
+});
 ```
 
 When reading them back, cast to string in the SELECT to avoid the same
@@ -125,8 +125,8 @@ const rs = await client.query({
            toString(dec128) AS decimal128
     FROM prices
   `,
-  format: 'JSONEachRow',
-})
+  format: "JSONEachRow",
+});
 ```
 
 ## Inserting a `UUID` into a `UInt128` column
@@ -142,11 +142,11 @@ clause**. With the row-oriented JSON formats the client uses (e.g.
 always pass `UInt128` as a string:
 
 ```ts
-import * as crypto from 'node:crypto'
+import * as crypto from "node:crypto";
 
 function uuidToUInt128(uuid: string): string {
   // 8-4-4-4-12 hex digits → 32 hex digits → BigInt → decimal string
-  return BigInt('0x' + uuid.replace(/-/g, '')).toString()
+  return BigInt("0x" + uuid.replace(/-/g, "")).toString();
 }
 
 await client.command({
@@ -154,14 +154,14 @@ await client.command({
     CREATE OR REPLACE TABLE events (id UInt128, description String)
     ENGINE MergeTree ORDER BY id
   `,
-})
+});
 
-const uuid = crypto.randomUUID()
+const uuid = crypto.randomUUID();
 await client.insert({
-  table: 'events',
-  format: 'JSONEachRow',
-  values: [{ id: uuidToUInt128(uuid), description: 'converted on the client' }],
-})
+  table: "events",
+  format: "JSONEachRow",
+  values: [{ id: uuidToUInt128(uuid), description: "converted on the client" }],
+});
 ```
 
 `UInt128` values are also too wide for a JS `number` when reading back — cast
@@ -181,15 +181,15 @@ await client.command({
     )
     ENGINE MergeTree ORDER BY id
   `,
-})
+});
 
 await client.insert({
-  table: 'events',
-  format: 'JSONEachRow',
-  values: [{ id_uuid: uuid, description: 'populated via EPHEMERAL column' }],
+  table: "events",
+  format: "JSONEachRow",
+  values: [{ id_uuid: uuid, description: "populated via EPHEMERAL column" }],
   // The ephemeral column must be listed so the DEFAULT on `id` is evaluated.
-  columns: ['id_uuid', 'description'],
-})
+  columns: ["id_uuid", "description"],
+});
 ```
 
 See `reference/insert-columns.md` for more on `EPHEMERAL` columns and why they

package/skills/clickhouse-js-node-coding/reference/ping.md

@@ -28,20 +28,20 @@ When answering "how do I health-check / readiness-probe ClickHouse?":
 ## Successful ping
 
 ```ts
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 
 const client = createClient({
   url: process.env.CLICKHOUSE_URL,
   password: process.env.CLICKHOUSE_PASSWORD,
-})
+});
 
-const pingResult = await client.ping()
+const pingResult = await client.ping();
 if (pingResult.success) {
-  console.info('ClickHouse is reachable')
+  console.info("ClickHouse is reachable");
 } else {
-  console.error('Ping failed:', pingResult.error)
+  console.error("Ping failed:", pingResult.error);
 }
-await client.close()
+await client.close();
 ```
 
 Use `ping()` to:
@@ -57,44 +57,44 @@ Use `ping()` to:
 `{ success: false, error: Error }`, so you can branch without `try/catch`:
 
 ```ts
-import type { PingResult } from '@clickhouse/client'
-import { createClient } from '@clickhouse/client'
+import type { PingResult } from "@clickhouse/client";
+import { createClient } from "@clickhouse/client";
 
 const client = createClient({
-  url: 'http://localhost:8100', // non-existing host
+  url: "http://localhost:8100", // non-existing host
   request_timeout: 50, // keep failure fast
-})
+});
 
-const pingResult = await client.ping()
+const pingResult = await client.ping();
 if (hasConnectionRefusedError(pingResult)) {
-  console.info('Connection refused, as expected')
+  console.info("Connection refused, as expected");
 } else {
-  console.error('Ping expected ECONNREFUSED, got:', pingResult)
+  console.error("Ping expected ECONNREFUSED, got:", pingResult);
 }
-await client.close()
+await client.close();
 
 function hasConnectionRefusedError(
   pingResult: PingResult,
-): pingResult is PingResult & { error: { code: 'ECONNREFUSED' } } {
+): pingResult is PingResult & { error: { code: "ECONNREFUSED" } } {
   return (
     !pingResult.success &&
-    'code' in pingResult.error &&
-    pingResult.error.code === 'ECONNREFUSED'
-  )
+    "code" in pingResult.error &&
+    pingResult.error.code === "ECONNREFUSED"
+  );
 }
 ```
 
 ## Mapping to an HTTP health endpoint
 
 ```ts
-app.get('/healthz', async (_req, res) => {
-  const r = await client.ping()
+app.get("/healthz", async (_req, res) => {
+  const r = await client.ping();
   if (r.success) {
-    res.status(200).json({ ok: true })
+    res.status(200).json({ ok: true });
   } else {
-    res.status(503).json({ ok: false, error: String(r.error) })
+    res.status(503).json({ ok: false, error: String(r.error) });
   }
-})
+});
 ```
 
 ## `ping()` vs `ping({ select: true })`
@@ -107,7 +107,7 @@ pipeline) will still return `{ success: true }` from a plain `ping()`.
 Pass `{ select: true }` to run a lightweight `SELECT 1` instead:
 
 ```ts
-const r = await client.ping({ select: true })
+const r = await client.ping({ select: true });
 // success only if the server is reachable AND auth is correct AND it can run queries
 ```
 

package/skills/clickhouse-js-node-coding/reference/query-parameters.md

@@ -26,10 +26,10 @@ ClickHouse uses `{name: Type}` placeholders — **not** `$1`, `?`, or `:name`.
 
 ```ts
 await client.query({
-  query: 'SELECT plus({a: Int32}, {b: Int32})',
-  format: 'JSONEachRow',
+  query: "SELECT plus({a: Int32}, {b: Int32})",
+  format: "JSONEachRow",
   query_params: { a: 10, b: 20 },
-})
+});
 ```
 
 The `Type` must be a valid ClickHouse type (`Int32`, `String`, `Date`,
@@ -41,16 +41,16 @@ Interpolating user input into the SQL string bypasses server-side escaping
 and opens the door to SQL injection:
 
 ```ts
-const userId = req.params.id
+const userId = req.params.id;
 
 // ❌ Dangerous — never do this with user-controlled values
-await client.query({ query: `SELECT * FROM users WHERE id = ${userId}` })
+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 },
-})
+});
 ```
 
 This is the most common mistake for users coming from PostgreSQL/MySQL. Call
@@ -59,7 +59,7 @@ it out explicitly when the user shows template-literal interpolation.
 ## Common types
 
 ```ts
-import { TupleParam } from '@clickhouse/client'
+import { TupleParam } from "@clickhouse/client";
 
 await client.query({
   query: `
@@ -79,27 +79,27 @@ await client.query({
       {var_ipv4: IPv4}                     AS var_ipv4,
       {var_null: Nullable(String)}         AS var_null
   `,
-  format: 'JSONEachRow',
+  format: "JSONEachRow",
   query_params: {
     var_int: 10,
-    var_float: '10.557',
-    var_str: 'hello',
+    var_float: "10.557",
+    var_str: "hello",
     var_array: [42, 144],
-    var_tuple: new TupleParam([42, 'foo']), // >= 1.9.0
+    var_tuple: new TupleParam([42, "foo"]), // >= 1.9.0
     var_map: new Map([
-      [42, ['a', 'b']],
-      [144, ['c', 'd']],
+      [42, ["a", "b"]],
+      [144, ["c", "d"]],
     ]), // >= 1.9.0
-    var_date: '2022-01-01',
-    var_datetime: '2022-01-01 12:34:56', // or a Date
-    var_datetime64_3: '2022-01-01 12:34:56.789', // or a Date
-    var_datetime64_9: '2022-01-01 12:34:56.123456789', // string for ns precision
-    var_decimal: '123.45', // string to avoid precision loss
-    var_uuid: '01234567-89ab-cdef-0123-456789abcdef',
-    var_ipv4: '192.168.0.1',
+    var_date: "2022-01-01",
+    var_datetime: "2022-01-01 12:34:56", // or a Date
+    var_datetime64_3: "2022-01-01 12:34:56.789", // or a Date
+    var_datetime64_9: "2022-01-01 12:34:56.123456789", // string for ns precision
+    var_decimal: "123.45", // string to avoid precision loss
+    var_uuid: "01234567-89ab-cdef-0123-456789abcdef",
+    var_ipv4: "192.168.0.1",
     var_null: null, // fixed in 0.0.16
   },
-})
+});
 ```
 
 ### Type-by-type tips
@@ -131,14 +131,14 @@ await client.query({
       'foo_\\'_bar' = {single_quote: String}    AS has_single_quote,
       'foo_\\_bar'  = {backslash: String}       AS has_backslash
   `,
-  format: 'JSONEachRow',
+  format: "JSONEachRow",
   query_params: {
-    tab: 'foo_\t_bar',
-    newline: 'foo_\n_bar',
+    tab: "foo_\t_bar",
+    newline: "foo_\n_bar",
     single_quote: "foo_'_bar",
-    backslash: 'foo_\\_bar',
+    backslash: "foo_\\_bar",
   },
-})
+});
 ```
 
 ## Common pitfalls

package/skills/clickhouse-js-node-coding/reference/select-formats.md

@@ -9,23 +9,23 @@
 Right answer for ~90% of selects when the result fits in memory.
 
 ```ts
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 
 interface Row {
-  number: string
+  number: string;
 }
 
-const client = createClient()
+const client = createClient();
 const rows = await client.query({
-  query: 'SELECT number FROM system.numbers LIMIT 5',
-  format: 'JSONEachRow',
-})
-const result = await rows.json<Row>() // Row[]
-result.forEach((r) => console.log(r))
+  query: "SELECT number FROM system.numbers LIMIT 5",
+  format: "JSONEachRow",
+});
+const result = await rows.json<Row>(); // Row[]
+result.forEach((r) => console.log(r));
 // { number: '0' }
 // { number: '1' }
 // ...
-await client.close()
+await client.close();
 ```
 
 `UInt64`/`Int64` and other 64-bit integers are returned as **strings**
@@ -41,16 +41,16 @@ Use `JSON` (or `JSONCompact`) when you need ClickHouse's response envelope
 `ResponseJSON<T>`:
 
 ```ts
-import { createClient, type ResponseJSON } from '@clickhouse/client'
+import { createClient, type ResponseJSON } from "@clickhouse/client";
 
-const client = createClient()
+const client = createClient();
 const rows = await client.query({
-  query: 'SELECT number FROM system.numbers LIMIT 2',
-  format: 'JSON',
-})
-const result = await rows.json<ResponseJSON<{ number: string }>>()
-console.info(result.meta, result.data, result.rows, result.statistics)
-await client.close()
+  query: "SELECT number FROM system.numbers LIMIT 2",
+  format: "JSON",
+});
+const result = await rows.json<ResponseJSON<{ number: string }>>();
+console.info(result.meta, result.data, result.rows, result.statistics);
+await client.close();
 ```
 
 > `JSON`, `JSONCompact`, `JSONStrings`, `JSONCompactStrings`,
@@ -64,10 +64,10 @@ Use `.text()` (not `.json()`) for raw textual formats:
 
 ```ts
 const rs = await client.query({
-  query: 'SELECT number, number * 2 AS doubled FROM system.numbers LIMIT 3',
-  format: 'CSVWithNames',
-})
-console.log(await rs.text())
+  query: "SELECT number, number * 2 AS doubled FROM system.numbers LIMIT 3",
+  format: "CSVWithNames",
+});
+console.log(await rs.text());
 ```
 
 Streaming raw text/Parquet line-by-line belongs in

package/skills/clickhouse-js-node-coding/reference/sessions.md

@@ -65,30 +65,30 @@ script, a background job, a single user's session that you've already manually
 serialized in the code).
 
 ```ts
-import { createClient } from '@clickhouse/client'
-import * as crypto from 'node:crypto'
+import { createClient } from "@clickhouse/client";
+import * as crypto from "node:crypto";
 
 const client = createClient({
   session_id: crypto.randomUUID(),
   max_open_connections: 1, // safeguard against concurrent-session errors
-})
+});
 
 await client.command({
-  query: 'CREATE TEMPORARY TABLE temporary_example (i Int32)',
-})
+  query: "CREATE TEMPORARY TABLE temporary_example (i Int32)",
+});
 
 await client.insert({
-  table: 'temporary_example',
+  table: "temporary_example",
   values: [{ i: 42 }, { i: 144 }],
-  format: 'JSONEachRow',
-})
+  format: "JSONEachRow",
+});
 
 const rs = await client.query({
-  query: 'SELECT * FROM temporary_example',
-  format: 'JSONEachRow',
-})
-console.info(await rs.json())
-await client.close()
+  query: "SELECT * FROM temporary_example",
+  format: "JSONEachRow",
+});
+console.info(await rs.json());
+await client.close();
 ```
 
 ## Session-level `SET` commands
@@ -97,37 +97,37 @@ await client.close()
 client, every subsequent call inherits the change.
 
 ```ts
-import { createClient } from '@clickhouse/client'
-import * as crypto from 'node:crypto'
+import { createClient } from "@clickhouse/client";
+import * as crypto from "node:crypto";
 
 const client = createClient({
   session_id: crypto.randomUUID(),
   max_open_connections: 1, // safe-guard against concurrent-session errors
-})
+});
 
 await client.command({
-  query: 'SET output_format_json_quote_64bit_integers = 0',
+  query: "SET output_format_json_quote_64bit_integers = 0",
   clickhouse_settings: { wait_end_of_query: 1 }, // ack before next call
-})
+});
 
 const rs1 = await client.query({
-  query: 'SELECT toInt64(42)',
-  format: 'JSONEachRow',
-})
+  query: "SELECT toInt64(42)",
+  format: "JSONEachRow",
+});
 // → 64-bit integers come back as numbers in this query
 
 await client.command({
-  query: 'SET output_format_json_quote_64bit_integers = 1',
+  query: "SET output_format_json_quote_64bit_integers = 1",
   clickhouse_settings: { wait_end_of_query: 1 },
-})
+});
 
 const rs2 = await client.query({
-  query: 'SELECT toInt64(144)',
-  format: 'JSONEachRow',
-})
+  query: "SELECT toInt64(144)",
+  format: "JSONEachRow",
+});
 // → 64-bit integers come back as strings again
 
-await client.close()
+await client.close();
 ```
 
 > **`wait_end_of_query: 1` matters here.** Without it, a `SET` on one

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

@@ -5,13 +5,13 @@
 Both request and response compression are supported. Only **GZIP** is supported (via zlib).
 
 ```js
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 const client = createClient({
   compression: {
     response: true,
     request: true,
   },
-})
+});
 ```
 
 ## Compression enabled but getting an error?

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

@@ -10,10 +10,10 @@ To receive them as numbers (use with caution — precision loss possible):
 
 ```js
 const resultSet = await client.query({
-  query: 'SELECT toUInt64(9007199254740993)',
-  format: 'JSONEachRow',
+  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.
@@ -30,18 +30,18 @@ const resultSet = await client.query({
     SELECT toString(my_decimal) AS my_decimal
     FROM my_table
   `,
-  format: 'JSONEachRow',
-})
+  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',
-})
+  table: "my_table",
+  values: [{ dec64: "123456789123456.789" }],
+  format: "JSONEachRow",
+});
 ```
 
 ## Inserting a UUID into a `UInt128` column fails (`CANNOT_PARSE_INPUT_ASSERTION_FAILED`)
@@ -55,19 +55,19 @@ Fix it with one of two patterns:
 **Pattern 1 — convert the UUID on the client and send it as a decimal string** (recommended). A JS `number` cannot hold 128 bits without precision loss, so always pass `UInt128` as a string:
 
 ```js
-import * as crypto from 'node:crypto'
+import * as crypto from "node:crypto";
 
 function uuidToUInt128(uuid) {
   // 8-4-4-4-12 hex digits → 32 hex digits → BigInt → decimal string
-  return BigInt('0x' + uuid.replace(/-/g, '')).toString()
+  return BigInt("0x" + uuid.replace(/-/g, "")).toString();
 }
 
-const uuid = crypto.randomUUID()
+const uuid = crypto.randomUUID();
 await client.insert({
-  table: 'events',
-  format: 'JSONEachRow',
-  values: [{ id: uuidToUInt128(uuid), description: 'converted on the client' }],
-})
+  table: "events",
+  format: "JSONEachRow",
+  values: [{ id: uuidToUInt128(uuid), description: "converted on the client" }],
+});
 ```
 
 Read `UInt128` back with `toString(id)` in the `SELECT` to avoid the same precision loss.
@@ -77,11 +77,11 @@ Read `UInt128` back with `toString(id)` in the `SELECT` to avoid the same precis
 ```js
 // CREATE TABLE events (id UInt128 DEFAULT id_uuid, id_uuid UUID EPHEMERAL, description String) ...
 await client.insert({
-  table: 'events',
-  format: 'JSONEachRow',
-  values: [{ id_uuid: uuid, description: 'populated via EPHEMERAL column' }],
-  columns: ['id_uuid', 'description'],
-})
+  table: "events",
+  format: "JSONEachRow",
+  values: [{ id_uuid: uuid, description: "populated via EPHEMERAL column" }],
+  columns: ["id_uuid", "description"],
+});
 ```
 
 ## Format Selection Quick Reference
@@ -106,8 +106,8 @@ await client.insert({
 - `DateTime` / `DateTime64` columns accept strings **or** JS `Date` objects. To use `Date` objects, set:
 
 ```js
-import { createClient } from '@clickhouse/client'
+import { createClient } from "@clickhouse/client";
 const client = createClient({
-  clickhouse_settings: { date_time_input_format: 'best_effort' },
-})
+  clickhouse_settings: { date_time_input_format: "best_effort" },
+});
 ```

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

@@ -5,20 +5,20 @@
 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'
+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'
+import { ClickHouseLogLevel, createClient } from "@clickhouse/client";
+import type { Logger } from "@clickhouse/client";
 
 class MyLogger implements Logger {
   debug({ module, message, args }) {
@@ -40,5 +40,5 @@ class MyLogger implements Logger {
 
 const client = createClient({
   log: { LoggerClass: MyLogger, level: ClickHouseLogLevel.INFO },
-})
+});
 ```