@clickhouse/client 1.18.4 → 1.18.5-head.50d1ed2.1

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

@@ -0,0 +1,141 @@
+# Insert Values, SQL Expressions, Dates, Decimals
+
+> **Applies to:** all versions. `wait_end_of_query: 1` is a server-side
+> setting available on every supported ClickHouse version.
+
+Backing examples:
+[`examples/node/coding/insert_from_select.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_from_select.ts),
+[`examples/node/coding/insert_values_and_functions.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_values_and_functions.ts),
+[`examples/node/coding/insert_js_dates.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_js_dates.ts),
+[`examples/node/coding/insert_decimals.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_decimals.ts).
+
+## `INSERT … SELECT` (no values payload)
+
+When the data already lives in ClickHouse, use `client.command()` with a raw
+`INSERT … SELECT`:
+
+```ts
+await client.command({
+  query: `
+    INSERT INTO target
+    SELECT '42', quantilesBFloat16State(0.5)(arrayJoin([toFloat32(10), toFloat32(20)]))
+  `,
+})
+```
+
+Use `command()` (not `insert()`) — there is no row payload to send.
+
+## `INSERT … VALUES` with SQL functions
+
+When you need `unhex(...)`, `toUUID(...)`, `now()`, or any other SQL
+function around a value, keep the SQL shape static and pass values with
+ClickHouse `{name: Type}` parameters. Run it via `command()` and set
+`wait_end_of_query: 1` for safety in clustered setups.
+
+```ts
+await client.command({
+  query: `
+    INSERT INTO events (id, timestamp, email, name)
+    VALUES (
+      unhex({id: String}),
+      {timestamp: DateTime},
+      {email: String},
+      {name: Nullable(String)}
+    )
+  `,
+  query_params: {
+    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
+you need to insert many ordinary JS rows, prefer `client.insert()` with
+`format: 'JSONEachRow'`; use this `command()` pattern when the SQL itself needs
+functions or expressions around the values.
+
+## Inserting JS `Date` objects
+
+JS `Date` objects work for `DateTime` and `DateTime64` columns once the
+server is set to accept ISO-8601 strings. Either set
+`date_time_input_format: 'best_effort'` per request, on the client, or
+session-wide.
+
+```ts
+await client.insert({
+  table: 'events',
+  format: 'JSONEachRow',
+  values: [{ id: '42', dt: new Date() }],
+  clickhouse_settings: {
+    date_time_input_format: 'best_effort',
+  },
+})
+```
+
+> JS `Date` objects do **not** work for the `Date` type (date-only) — pass
+> `'YYYY-MM-DD'` strings for that.
+
+## Inserting `Decimal*` values
+
+Decimals must be passed as **strings** in JSON formats to avoid precision
+loss in JavaScript:
+
+```ts
+await client.command({
+  query: `
+    CREATE OR REPLACE TABLE prices (
+      id     UInt32,
+      dec32  Decimal(9, 2),
+      dec64  Decimal(18, 3),
+      dec128 Decimal(38, 10),
+      dec256 Decimal(76, 20)
+    )
+    ENGINE MergeTree ORDER BY id
+  `,
+})
+
+await client.insert({
+  table: 'prices',
+  format: 'JSONEachRow',
+  values: [
+    {
+      id: 1,
+      dec32: '1234567.89',
+      dec64: '123456789123456.789',
+      dec128: '1234567891234567891234567891.1234567891',
+      dec256:
+        '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
+    },
+  ],
+})
+```
+
+When reading them back, cast to string in the SELECT to avoid the same
+precision loss:
+
+```ts
+const rs = await client.query({
+  query: `
+    SELECT toString(dec64)  AS decimal64,
+           toString(dec128) AS decimal128
+    FROM prices
+  `,
+  format: 'JSONEachRow',
+})
+```
+
+## Common pitfalls
+
+- **Passing decimals as JS `number`s.** Anything beyond `Number.MAX_SAFE_INTEGER`
+  silently loses precision before it ever reaches the server.
+- **Using `client.insert()` for `INSERT … SELECT`.** There's nothing to
+  upload — use `client.command()` with the full SQL.
+- **Forgetting `date_time_input_format: 'best_effort'`** when inserting
+  `Date` objects (or ISO strings). The default input format does not accept
+  ISO-8601 with the `T`/`Z` separators.
+- **Hand-building `VALUES` with user input.** Always parameterize user data;
+  see `reference/query-parameters.md`.

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

@@ -0,0 +1,120 @@
+# Ping the Server
+
+> **Applies to:** all versions. `ping()` returns a discriminated
+> `PingResult = { success: true } | { success: false, error: Error }` —
+> it does **not** throw on connection failures.
+
+Backing examples:
+[`examples/node/coding/ping_existing_host.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/ping_existing_host.ts),
+[`examples/node/coding/ping_non_existing_host.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/ping_non_existing_host.ts).
+
+## Successful ping
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: process.env.CLICKHOUSE_URL,
+  password: process.env.CLICKHOUSE_PASSWORD,
+})
+
+const pingResult = await client.ping()
+if (pingResult.success) {
+  console.info('ClickHouse is reachable')
+} else {
+  console.error('Ping failed:', pingResult.error)
+}
+await client.close()
+```
+
+Use `ping()` to:
+
+- Probe ClickHouse at application startup.
+- Wake up a ClickHouse Cloud instance that may be idling (a ping is enough to
+  bring it out of sleep).
+- Implement a `/healthz` / readiness endpoint.
+
+## Failure: host unreachable
+
+`ping()` does **not** throw — it resolves with
+`{ success: false, error: Error }`, so you can branch without `try/catch`:
+
+```ts
+import type { PingResult } from '@clickhouse/client'
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: 'http://localhost:8100', // non-existing host
+  request_timeout: 50, // keep failure fast
+})
+
+const pingResult = await client.ping()
+if (hasConnectionRefusedError(pingResult)) {
+  console.info('Connection refused, as expected')
+} else {
+  console.error('Ping expected ECONNREFUSED, got:', pingResult)
+}
+await client.close()
+
+function hasConnectionRefusedError(
+  pingResult: PingResult,
+): pingResult is PingResult & { error: { code: 'ECONNREFUSED' } } {
+  return (
+    !pingResult.success &&
+    '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()
+  if (r.success) {
+    res.status(200).json({ ok: true })
+  } else {
+    res.status(503).json({ ok: false, error: String(r.error) })
+  }
+})
+```
+
+## `ping()` vs `ping({ select: true })`
+
+The default `ping()` hits ClickHouse's `/ping` HTTP endpoint — it verifies
+network connectivity but **does not check credentials or query processing**.
+A server that is reachable but has a bad password (or a broken query
+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 })
+// success only if the server is reachable AND auth is correct AND it can run queries
+```
+
+|                         | `client.ping()` | `client.ping({ select: true })` |
+| ----------------------- | --------------- | ------------------------------- |
+| Endpoint                | `/ping` (HTTP)  | `SELECT 1` query                |
+| Checks auth             | **No**          | Yes                             |
+| Checks query processing | No              | **Yes**                         |
+| Overhead                | Minimal         | Slightly higher                 |
+
+**When to use which:**
+
+- **Liveness probe** (is the process alive?) — plain `ping()` is fine.
+- **Readiness probe** (can it serve traffic?) — use `ping({ select: true })`
+  so the probe fails if credentials are wrong or the query layer is broken.
+- **Waking a ClickHouse Cloud idle instance** — plain `ping()` is enough.
+
+## Common pitfalls
+
+- **Do not wrap `ping()` in `try/catch` as your only check.** It resolves on
+  failure; the `success` boolean is the source of truth.
+- **Lower `request_timeout` if you want pings to fail fast** (the example
+  above uses `50` ms). The default is high enough to be unsuitable for
+  liveness probes.
+- **Plain `ping()` does not check credentials.** If auth is part of what you
+  want to verify, use `ping({ select: true })`.
+- For ping that times out specifically, see the troubleshooting skill.

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

@@ -0,0 +1,152 @@
+# Query Parameter Binding
+
+> **Applies to:** all versions. NULL parameter binding fixed in `0.0.16`.
+> Special-character (tab/newline/quote/backslash) binding `>= 0.3.1`.
+> `TupleParam` and JS `Map` parameters `>= 1.9.0`. Boolean formatting in
+> `Array`/`Tuple`/`Map` parameters fixed in `>= 1.13.0`. `BigInt` query
+> parameters `>= 1.15.0`.
+
+Backing examples:
+[`examples/node/coding/query_with_parameter_binding.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/query_with_parameter_binding.ts),
+[`examples/node/coding/query_with_parameter_binding_special_chars.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/query_with_parameter_binding_special_chars.ts).
+
+## Answer checklist
+
+When the user passes user-controlled values into SQL:
+
+- Use ClickHouse `{name: Type}` placeholders and a `query_params` object.
+- Explicitly call template-literal/string interpolation of user input a
+  **SQL injection risk**.
+- Do not suggest PostgreSQL/MySQL-style `$1`, `?`, or `:name` placeholders.
+- Pick the placeholder type to match the ClickHouse column type (`String`,
+  `Date`, `DateTime`, `Nullable(T)`, etc.).
+
+## Syntax: `{name: Type}`
+
+ClickHouse uses `{name: Type}` placeholders — **not** `$1`, `?`, or `:name`.
+
+```ts
+await client.query({
+  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`,
+`Array(UInt32)`, `Tuple(Int32, String)`, `Map(K, V)`, `Nullable(T)`, etc.).
+
+## ⚠️ Never use template literals for user values
+
+Interpolating user input into the SQL string bypasses server-side escaping
+and opens the door to SQL injection:
+
+```ts
+// ❌ 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 },
+})
+```
+
+This is the most common mistake for users coming from PostgreSQL/MySQL. Call
+it out explicitly when the user shows template-literal interpolation.
+
+## Common types
+
+```ts
+import { TupleParam } from '@clickhouse/client'
+
+await client.query({
+  query: `
+    SELECT
+      {var_int: Int32}                     AS var_int,
+      {var_float: Float32}                 AS var_float,
+      {var_str: String}                    AS var_str,
+      {var_array: Array(Int32)}            AS var_array,
+      {var_tuple: Tuple(Int32, String)}    AS var_tuple,
+      {var_map: Map(Int, Array(String))}   AS var_map,
+      {var_date: Date}                     AS var_date,
+      {var_datetime: DateTime}             AS var_datetime,
+      {var_datetime64_3: DateTime64(3)}    AS var_datetime64_3,
+      {var_datetime64_9: DateTime64(9)}    AS var_datetime64_9,
+      {var_decimal: Decimal(9, 2)}         AS var_decimal,
+      {var_uuid: UUID}                     AS var_uuid,
+      {var_ipv4: IPv4}                     AS var_ipv4,
+      {var_null: Nullable(String)}         AS var_null
+  `,
+  format: 'JSONEachRow',
+  query_params: {
+    var_int: 10,
+    var_float: '10.557',
+    var_str: 'hello',
+    var_array: [42, 144],
+    var_tuple: new TupleParam([42, 'foo']), // >= 1.9.0
+    var_map: new Map([
+      [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_null: null, // fixed in 0.0.16
+  },
+})
+```
+
+### Type-by-type tips
+
+- **Decimals** — pass as strings to avoid JS number precision loss.
+- **`DateTime64(>3)`** — pass as a string; JS `Date` only has millisecond
+  precision and will lose sub-millisecond digits.
+- **`DateTime64`** — strings can also be UNIX timestamps, including
+  fractional ones (e.g., `'1651490755.123456789'`).
+- **`BigInt`** — supported in `query_params` since `>= 1.15.0`. On older
+  clients, pass as a string.
+- **`Tuple(...)`** — wrap in `new TupleParam([...])` (`>= 1.9.0`); on older
+  clients, build the literal manually as a string.
+- **`Map(K, V)`** — pass a JS `Map` (`>= 1.9.0`); on older clients, build
+  it manually.
+- **`Nullable(T)`** — pass `null` directly (`>= 0.0.16`).
+
+## Special characters in string parameters (`>= 0.3.1`)
+
+Tabs, newlines, carriage returns, single quotes, and backslashes are
+escaped automatically by the client — just pass the JS string as-is:
+
+```ts
+await client.query({
+  query: `
+    SELECT
+      'foo_\t_bar'  = {tab: String}             AS has_tab,
+      'foo_\n_bar'  = {newline: String}         AS has_newline,
+      'foo_\\'_bar' = {single_quote: String}    AS has_single_quote,
+      'foo_\\_bar'  = {backslash: String}       AS has_backslash
+  `,
+  format: 'JSONEachRow',
+  query_params: {
+    tab: 'foo_\t_bar',
+    newline: 'foo_\n_bar',
+    single_quote: "foo_'_bar",
+    backslash: 'foo_\\_bar',
+  },
+})
+```
+
+## Common pitfalls
+
+- **`$1` / `?` / `:name` placeholders.** None work — use `{name: Type}`.
+- **Forgetting the type in the placeholder.** `{id}` is a syntax error;
+  it must be `{id: UInt32}`.
+- **Stringifying tuples/maps manually on `>= 1.9.0`.** Use `TupleParam`
+  and `Map` — both serialize correctly and respect special characters.
+- **Boolean array/tuple/map elements before `1.13.0`.** Boolean formatting
+  was fixed in 1.13.0 — earlier versions may misformat them.

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

@@ -0,0 +1,111 @@
+# Select Data Formats
+
+> **Applies to:** all versions. `JSONEachRowWithProgress` requires client
+> `>= 1.7.0`; see the in-repo performance examples under
+> `examples/node/performance/`.
+
+Backing examples:
+[`examples/node/coding/select_json_each_row.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/select_json_each_row.ts),
+[`examples/node/coding/select_data_formats_overview.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/select_data_formats_overview.ts),
+[`examples/node/coding/select_json_with_metadata.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/select_json_with_metadata.ts).
+
+## Default choice: `JSONEachRow` → `.json<T>()`
+
+Right answer for ~90% of selects when the result fits in memory.
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+interface Row {
+  number: string
+}
+
+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))
+await client.close()
+```
+
+`UInt64`/`Int64` and other 64-bit integers are returned as **strings**
+when `output_format_json_quote_64bit_integers=1`, to avoid JS precision
+loss. If that setting is `0`, they may be returned as unquoted JSON
+numbers instead. Note that in ClickHouse `>= 25.8`, this setting can
+default to `0`; see the troubleshooting skill for ways to control that.
+
+## Single-document `JSON` format with metadata
+
+Use `JSON` (or `JSONCompact`) when you need ClickHouse's response envelope
+(rows + meta + statistics + row count). Type the result with
+`ResponseJSON<T>`:
+
+```ts
+import { createClient, type ResponseJSON } from '@clickhouse/client'
+
+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()
+```
+
+> `JSON`, `JSONCompact`, `JSONStrings`, `JSONCompactStrings`,
+> `JSONColumnsWithMetadata`, `JSONObjectEachRow` are **single-document**
+> formats — they cannot be streamed. Use a `*EachRow` variant if you want
+> to stream.
+
+## Selecting raw text (CSV / TSV / CustomSeparated)
+
+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())
+```
+
+Streaming raw text/Parquet line-by-line belongs in
+[`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance)
+— in particular, Parquet exports use `client.exec()` and pipe the raw
+response stream rather than `ResultSet.stream()` (see
+[`select_parquet_as_file.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_parquet_as_file.ts)).
+
+## Format chooser
+
+| Use case                                                 | Format                                                                                                                                                     |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Read rows as JS objects                                  | `JSONEachRow` _(default)_                                                                                                                                  |
+| Read rows as positional tuples (smaller payload)         | `JSONCompactEachRow`                                                                                                                                       |
+| Need `meta` / `statistics` / `rows` envelope             | `JSON` or `JSONCompact` + `ResponseJSON<T>`                                                                                                                |
+| Read all values as strings (avoid number-precision loss) | `JSONStringsEachRow` / `JSONCompactStringsEachRow`                                                                                                         |
+| Stream very large result                                 | `JSONEachRow` / `JSONCompactEachRow` (see [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance)) |
+| Export to CSV/TSV/Parquet                                | `CSV*`, `TabSeparated*`, `Parquet` (see [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance))   |
+
+## ResultSet methods
+
+| Method               | Returns                                          | Notes                                                                                                                                                                                                                                                                                                                                |
+| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `await rs.json<T>()` | `T[]` for `*EachRow`, single-doc shape otherwise | Buffers the full response                                                                                                                                                                                                                                                                                                            |
+| `await rs.text()`    | `string`                                         | Buffers the full response — for textual formats only (CSV/TSV/etc.)                                                                                                                                                                                                                                                                  |
+| `rs.stream()`        | Node `Readable` of `Row[]` chunks                | Use for large newline-delimited results (`JSONEachRow`/`JSONCompactEachRow`/`CSV`/`TSV`); **not** suitable for binary formats like `Parquet` — for those, use `client.exec()` and pipe the raw response stream (see [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance)) |
+| `rs.close()`         | `void` (synchronous)                             | Always call if you obtained `stream()` and stop reading early                                                                                                                                                                                                                                                                        |
+
+## Common pitfalls
+
+- **Calling `.json()` on a `JSON` (single-doc) result and expecting an
+  array.** You get a `ResponseJSON<T>` object; the rows are under
+  `.data`. Use `JSONEachRow` if you want a flat array.
+- **Leaving a `stream()` half-consumed.** This is a top cause of
+  `ECONNRESET` on the _next_ request — fully iterate the stream or call
+  `resultSet.close()` (synchronous — no `await`). (Diagnosis details live in the
+  troubleshooting skill.)
+- **Reaching for `.json()` on a CSV/TSV result.** Use `.text()` (or
+  `.stream()` for large results).

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

@@ -0,0 +1,152 @@
+# Sessions and Temporary Tables
+
+> **Applies to:** all versions. `session_id` is a server-level concept; the
+> client just forwards it on every request that names it.
+
+Backing examples:
+[`examples/node/coding/session_id_and_temporary_tables.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/session_id_and_temporary_tables.ts),
+[`examples/node/coding/session_level_commands.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/session_level_commands.ts).
+
+## When you need a session
+
+Use a `session_id` whenever multiple calls must share **server-side state**:
+
+- `CREATE TEMPORARY TABLE` (the table only exists within its session).
+- `SET <setting> = <value>` to apply for subsequent queries on the same
+  session.
+- Any other server feature scoped per session (e.g., session-scoped
+  variables in newer ClickHouse versions).
+
+## ⚠️ `session_id` and concurrency
+
+ClickHouse **rejects concurrent queries within the same session** — if two
+requests arrive at the server at the same time sharing the same `session_id`,
+the second one gets an error like
+`"Session is locked by a concurrent client"`. This has two practical
+implications:
+
+1. **Do not set `session_id` on a global / module-static client** that handles
+   concurrent requests (e.g., an Express app's shared client). Every
+   in-flight request would share the same session and collide under load.
+2. **If you do set `session_id` on a client**, restrict its concurrency:
+   set `max_open_connections: 1` so at most one request is in flight at a
+   time, turning the pool into a serial queue. This is fine for a
+   dedicated per-workflow client but wrong for a shared application client.
+
+The right pattern for application code: create a **short-lived client** (or
+use per-request `session_id`) scoped to a single logical workflow, not to
+the entire process.
+
+## Per-client `session_id`
+
+Appropriate when **one client handles exactly one sequential workflow** (a
+script, a background job, a single user's session that you've already
+serialized).
+
+```ts
+import { createClient } from '@clickhouse/client'
+import * as crypto from 'node:crypto'
+
+const client = createClient({
+  session_id: crypto.randomUUID(),
+  max_open_connections: 1, // prevent concurrent-session errors
+})
+
+await client.command({
+  query: 'CREATE TEMPORARY TABLE temporary_example (i Int32)',
+})
+
+await client.insert({
+  table: 'temporary_example',
+  values: [{ i: 42 }, { i: 144 }],
+  format: 'JSONEachRow',
+})
+
+const rs = await client.query({
+  query: 'SELECT * FROM temporary_example',
+  format: 'JSONEachRow',
+})
+console.info(await rs.json())
+await client.close()
+```
+
+## Session-level `SET` commands
+
+`SET` only persists within a session. With `session_id` defined on the
+client, every subsequent call inherits the change.
+
+```ts
+import { createClient } from '@clickhouse/client'
+import * as crypto from 'node:crypto'
+
+const client = createClient({
+  session_id: crypto.randomUUID(),
+  max_open_connections: 1, // prevent concurrent-session errors
+})
+
+await client.command({
+  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',
+})
+// → 64-bit integers come back as numbers in this query
+
+await client.command({
+  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',
+})
+// → 64-bit integers come back as strings again
+
+await client.close()
+```
+
+> **`wait_end_of_query: 1` matters here.** Without it, a `SET` on one
+> connection in the pool may not yet be applied when the next query lands
+> on the same socket.
+
+## Per-request `session_id`
+
+You can also pass `session_id` on a single `query()` / `insert()` /
+`command()` call to override (or set) it for that one request.
+
+## ⚠️ Sessions and load balancers / ClickHouse Cloud
+
+Sessions are bound to a **specific ClickHouse node**. If a load balancer in
+front of ClickHouse routes consecutive requests to different nodes, the
+temporary table / `SET` won't be visible — you'll get
+`UNKNOWN_TABLE` / surprising results.
+
+Mitigations:
+
+- Talk to a single node directly.
+- For ClickHouse Cloud, use [replica-aware
+  routing](https://clickhouse.com/docs/manage/replica-aware-routing).
+- Avoid sessions for cross-node workflows; persist intermediate state in a
+  regular (non-temporary) table instead.
+
+## Common pitfalls
+
+- **Forgetting `session_id` and being surprised that
+  `CREATE TEMPORARY TABLE` "disappears."** Without a session, every request
+  may land on a different connection / server context.
+- **Setting `session_id` on a shared application client.** Under concurrent
+  load, two in-flight requests will share the same session and one will fail
+  with `"Session is locked by a concurrent client"`. Use per-request
+  `session_id` or a dedicated short-lived client instead.
+- **Reusing the same `session_id` across unrelated workflows.** A second
+  session-using consumer will trip over your temporary tables and `SET`
+  values. Generate a fresh UUID per logical session.
+- **Leaving session state pinned for the lifetime of the process.** If
+  long-lived clients accumulate `SET` / temp-table state, consider creating
+  a short-lived sub-client with its own `session_id` for the unit of work.
+- **Skipping `wait_end_of_query: 1` on `SET`** — race conditions between
+  `SET` and the next query can show up under load.