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

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.18.4";
+declare const _default: "1.18.5-head.50d1ed2.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';
+exports.default = '1.18.5-head.50d1ed2.1';
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;AAAA,kBAAe,QAAQ,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;AAAA,kBAAe,uBAAuB,CAAA"}

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",
+  "version": "1.18.5-head.50d1ed2.1",
   "license": "Apache-2.0",
   "keywords": [
     "clickhouse",
@@ -40,7 +40,7 @@
     "build": "rm -rf dist; tsc"
   },
   "dependencies": {
-    "@clickhouse/client-common": "1.18.4"
+    "@clickhouse/client-common": "1.18.5-head.50d1ed2.1"
   },
   "devDependencies": {
     "simdjson": "^0.9.2"

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

@@ -0,0 +1,146 @@
+---
+name: clickhouse-js-node-coding
+description: >
+  Write idiomatic application code with the ClickHouse Node.js client
+  (`@clickhouse/client`). Use this skill whenever a user is *building* against
+  the Node.js client — configuring the client, pinging, inserting rows in JSON
+  or raw formats, selecting and parsing results, binding query parameters,
+  managing sessions and temporary tables, working with data types like
+  `Date`/`DateTime`/`Decimal`/`Time`/`Time64`/`Dynamic`/`Variant`/`JSON`, or
+  customizing JSON parsing. Trigger on phrases like "how do I insert…", "how
+  do I select…", "what format should I use…", "how do I parameterize…", "how
+  do I configure the client…". Do NOT use for browser/Web client code, for
+  performance/streaming/Parquet questions (see `examples/node/performance/`),
+  or for diagnosing errors and unexpected behavior (see
+  clickhouse-js-node-troubleshooting).
+---
+
+# ClickHouse Node.js Client — Coding
+
+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. **Match the user's intent** to a row in the Task Index below and read the
+   corresponding reference file before writing code. After reading it, scan any
+   **Answer checklist** in that reference and make sure the final answer covers
+   each relevant item; those checklists capture details users usually need but
+   are easy to omit in short answers.
+2. **Always import from `@clickhouse/client`** (never `@clickhouse/client-web`)
+   and create a single client with `createClient({ url })` or rely on
+   supported defaults when appropriate. Close it with `await client.close()`
+   during graceful shutdown.
+3. **Prefer `JSONEachRow` for typical row inserts/selects** unless the user
+   has already chosen another format or is streaming raw bytes (CSV / TSV /
+   Parquet — see `examples/node/performance/`).
+   **Note on `clickhouse_settings`:** settings passed to `createClient` are
+   defaults for every request; they can be overridden per-call by passing
+   `clickhouse_settings` directly to `insert()`, `query()`, or `command()`.
+   Always mention this when the user configures settings at the client level.
+4. **Always use `query_params` for user-supplied values** — never template-
+   literal-interpolate them into SQL. See `reference/query-parameters.md`.
+5. **Pick the right method for the job:**
+   - `client.insert()` — write rows.
+   - `client.query()` + `resultSet.json()` / `.text()` / `.stream()` — read
+     rows that return data.
+   - `client.command()` — DDL and other statements that don't return rows
+     (`CREATE`, `DROP`, `TRUNCATE`, `ALTER`, `SET` in a session, etc.).
+   - `client.exec()` — when you need the raw response stream of an arbitrary
+     statement (rare in coding scenarios).
+   - `client.ping()` — health check; returns `{ success, error? }`, never
+     throws on connection failure.
+6. **Note version constraints** when relevant. Examples:
+   - `pathname` config option: client `>= 1.0.0`.
+   - `BigInt` values in `query_params`: client `>= 1.15.0`.
+   - `TupleParam` and JS `Map` in `query_params`: client `>= 1.9.0`.
+   - Configurable `json.parse` / `json.stringify`: client `>= 1.14.0`.
+   - `Time` / `Time64` data types: ClickHouse server `>= 25.6`.
+   - `Dynamic` / `Variant` / new `JSON` types: ClickHouse server `>= 24.1` /
+     `24.5` / `24.8` (no longer experimental since `25.3`).
+7. **Show a runnable snippet**, not pseudo-code. The examples in
+   [`examples/node/coding/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/coding)
+   are all self-contained and runnable against the repo's `docker-compose up`
+   setup — pattern your snippet after them.
+
+---
+
+## Task Index
+
+Identify the user's task and read the matching reference file.
+
+| Task                                                     | Triggers / symptoms                                                                                        | Reference file                      |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| **Configure / connect the client**                       | Building a `createClient` call, URL parameters, `clickhouse_settings`, default format, custom HTTP headers | `reference/client-configuration.md` |
+| **Ping the server**                                      | Health checks, readiness probes, "is ClickHouse up?"                                                       | `reference/ping.md`                 |
+| **Choose an insert format**                              | "Which format should I use to insert?", JSON vs raw, `JSONEachRow` vs `JSON` vs `JSONObjectEachRow`        | `reference/insert-formats.md`       |
+| **Insert into a subset of columns / different database** | `insert({ columns })`, excluding columns, ephemeral columns, cross-DB inserts                              | `reference/insert-columns.md`       |
+| **Insert values, expressions, dates, decimals**          | `INSERT … VALUES` with SQL functions, `Date`/`DateTime` from JS, `Decimal` precision, `INSERT … SELECT`    | `reference/insert-values.md`        |
+| **Async inserts (server-side batching)**                 | `async_insert=1`, fire-and-forget vs wait-for-ack                                                          | `reference/async-insert.md`         |
+| **Select and parse results**                             | `JSONEachRow` reads, `JSON` with metadata, picking a select format                                         | `reference/select-formats.md`       |
+| **Parameterize queries**                                 | Binding values, special characters / escaping, "SQL injection?", `{name: Type}` syntax                     | `reference/query-parameters.md`     |
+| **Sessions & temporary tables**                          | `session_id`, `CREATE TEMPORARY TABLE`, per-session `SET` commands                                         | `reference/sessions.md`             |
+| **Modern data types**                                    | `Dynamic`, `Variant`, `JSON` (object), `Time`, `Time64`                                                    | `reference/data-types.md`           |
+| **Custom JSON parse/stringify**                          | Plug in `JSONBig` / `safe-stable-stringify` / a `BigInt`-aware serializer                                  | `reference/custom-json.md`          |
+
+---
+
+## Conventions used in answers
+
+- Always show `import { createClient } from '@clickhouse/client'` (Node, never
+  Web). For things that require a runtime API, prefer `node:` built-ins
+  (e.g., `import * as crypto from 'node:crypto'`).
+- Always `await client.close()` at the end of self-contained snippets; in
+  long-running services, close on graceful shutdown.
+- Prefer top-level `await` in snippets to match the style of
+  `examples/node/coding/*.ts`.
+- For inserts, prefer `format: 'JSONEachRow'` and `values: [...]` unless the
+  user's scenario requires otherwise.
+- For selects, prefer `await (await client.query({...})).json<RowType>()` for
+  small / medium result sets; for streaming, see `examples/node/performance/`.
+- When showing parameter binding, use ClickHouse's native `{name: Type}`
+  syntax — never `$1`, `?`, or `:name`.
+- For DDL inside a cluster or behind a load balancer, set
+  `clickhouse_settings: { wait_end_of_query: 1 }` on the `command()` call so
+  the server only acknowledges after the change is applied. See
+  https://clickhouse.com/docs/en/interfaces/http/#response-buffering.
+
+---
+
+## Out of scope
+
+This skill covers day-to-day coding against `@clickhouse/client` (Node).
+The following topics are intentionally **not** covered here:
+
+- **Errors, hangs, type mismatches, proxy pathname surprises, log silence,
+  socket hang-ups, `ECONNRESET`** → use the
+  `clickhouse-js-node-troubleshooting` skill.
+- **Streaming, Parquet, file streams, server-side bulk moves, progress
+  streaming, async-insert throughput tuning** — see
+  [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance).
+- **TLS, RBAC / read-only users, deeper SQL-injection guidance** — see
+  [`examples/node/security/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/security).
+- **`CREATE TABLE` patterns, deployment-shaped connection strings,
+  replication / sharding choices** — see
+  [`examples/node/schema-and-deployments/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/schema-and-deployments).
+- **Browser, Web Worker, Next.js Edge, Cloudflare Workers** — use
+  `@clickhouse/client-web` and see
+  [`examples/web/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/web).
+
+---
+
+## Still Stuck?
+
+- [`examples/node/coding/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/coding) — the runnable corpus this skill is built on.
+- [ClickHouse JS client docs](https://clickhouse.com/docs/integrations/javascript)
+- [ClickHouse supported formats](https://clickhouse.com/docs/interfaces/formats)
+- [ClickHouse data types](https://clickhouse.com/docs/sql-reference/data-types)

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

@@ -0,0 +1,103 @@
+{
+  "skill_name": "clickhouse-js-node-coding",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "I'm setting up clickhouse client in a Node service. I want to point it at https://my.host:8124, use database 'analytics', user 'bob' / password 'secret', set application name 'my_app', and turn on async_insert without waiting for ack. What's the cleanest way to express that?",
+      "expected_output": "A createClient call (Node, not Web) that sets url, username/password (or embeds them in the URL), database, application, and clickhouse_settings: { async_insert: 1, wait_for_async_insert: 0 }. Optionally mentions the equivalent URL-parameter form (ch_async_insert=1&ch_wait_for_async_insert=0) and that URL params override the config object.",
+      "files": [],
+      "expectations": [
+        "Uses createClient from @clickhouse/client (Node, not Web).",
+        "Either passes a single URL string with auth + ?ch_async_insert=1&ch_wait_for_async_insert=0, or a config object with database, username, password, application, clickhouse_settings.",
+        "Mentions or implies that URL parameters override the config object if both are provided.",
+        "Does not suggest using URL parameters in code and instead suggests that the URL should be read from environment variables or a config file.",
+        "Does not construct the URL with parameters directly in code neither using string concatenation nor query objects.",
+        "Suggests using `await client.close()` during graceful shutdown.",
+        "Suggests that settings in `clickhouse_settings` can be overridden per-query by passing them inside the individual `insert()` or `query()` call for finer control."
+      ]
+    },
+    {
+      "id": 1,
+      "prompt": "How do I do a health check against ClickHouse from Node? I want to return 200/503 from an Express endpoint based on whether ClickHouse is reachable.",
+      "expected_output": "Use await client.ping(), branch on { success } (no try/catch needed) — return 200 on success and 503 on failure, optionally surfacing the error.",
+      "files": [],
+      "expectations": [
+        "Uses await client.ping() and reads { success, error } directly — does NOT wrap it in try/catch as the only check.",
+        "Maps success === true to 200 and success === false to 503.",
+        "Suggests lowering request_timeout to make the probe fail fast.",
+        "Explains the difference between `client.ping()` (checks connectivity only and ignores credentials by default) and `client.ping({ select: true })` (lightweight query that also checks auth and query processing) and when to use each."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I have an array of about 10k plain JS objects I want to insert into a MergeTree table. What's the right format and call?",
+      "expected_output": "client.insert with format: 'JSONEachRow' and values: <array>. No streaming / Parquet needed for this size.",
+      "files": [],
+      "expectations": [
+        "Uses client.insert({ table, values, format: 'JSONEachRow' }).",
+        "Notes that the array can be passed directly to values — no need to stringify or stream for a few thousand rows.",
+        "Does NOT recommend a streaming/Parquet flow for this size.",
+        "Mentions `JSONCompact*` formats as an alternative for bigger payloads"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "My table has columns (id, name, created_at, internal_hash) but the rows I have only contain id and name. How do I insert just those two columns?",
+      "expected_output": "Use the columns option on client.insert: either columns: ['id', 'name'] (allowlist) or columns: { except: ['created_at', 'internal_hash'] } (excludelist). Omitted columns get their declared defaults.",
+      "files": [],
+      "expectations": [
+        "Uses client.insert with the columns: ['id', 'name'] option.",
+        "Mentions the alternative columns: { except: [...] } form.",
+        "Notes that omitted columns will receive their server-side defaults."
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "I want to call: SELECT * FROM users WHERE country = '<user input>' AND signup_date > '<user input>'. How should I pass those values from JS?",
+      "expected_output": "Use parameterized queries with the ClickHouse {name: Type} syntax and query_params: { country: ..., signup_date: ... }. Explicitly warn against template-literal interpolation (SQL injection).",
+      "files": [],
+      "expectations": [
+        "Uses {name: Type} parameter syntax (e.g., {country: String}, {signup_date: Date}) and query_params.",
+        "Explicitly warns against template-literal interpolation as a SQL injection risk.",
+        "Does NOT suggest $1/?/:name placeholders."
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "I'm doing CREATE TEMPORARY TABLE and then SELECT from it in a follow-up call. They keep disappearing between calls. What am I missing?",
+      "expected_output": "Temporary tables are scoped to a session — set a stable session_id (e.g., crypto.randomUUID()) on the client (or per-call) so consecutive requests share server-side state. Also flag the load-balancer/Cloud caveat (replica-aware routing).",
+      "files": [],
+      "expectations": [
+        "Explains that temporary tables are scoped to a session and require a stable session_id across calls.",
+        "Shows setting session_id either on createClient or via per-call session_id.",
+        "Mentions the load-balancer / ClickHouse Cloud caveat (sessions are pinned to a node; recommend replica-aware routing or a single-node connection).",
+        "Explicitly explains that parallel calls with the same session_id will result in an error as ClickHouse does not allow concurrent queries within the same session_id.",
+        "Explicitly advises against using session_id in client configuration for a global / module static client",
+        "When session_id is used as a client option it should suggest configuring the maximum number of connections to 1 to minimize concurrency issues at the client level."
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "I'm running 25.x ClickHouse. I want to store a JSON object per row and read it back as a real JS object, not a JSON string. How do I do that with the Node client?",
+      "expected_output": "Use the new JSON column type (>= 24.8, no longer experimental since 25.3). CREATE TABLE with a JSON column, insert with format: 'JSONEachRow' passing JS objects, select with JSONEachRow — values come back as parsed JS objects with no manual JSON.parse.",
+      "files": [],
+      "expectations": [
+        "Uses the JSON column type and format: 'JSONEachRow' for both insert and select.",
+        "Inserts a real JS object as the column value (no JSON.stringify) and shows it returns as a parsed object.",
+        "Mentions the relevant ClickHouse server version (>= 24.8 introduced; non-experimental since 25.3) and, if needed on older servers, allow_experimental_json_type."
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "Our IDs are UInt64 and we don't want them coming back as strings or losing precision.",
+      "expected_output": "Yes — pass a custom { parse, stringify } via the json config option (>= 1.14.0). Show wiring up json-bigint (or similar) so 64-bit integers are parsed as BigInt. Mention output_format_json_quote_64bit_integers: 0 so the server emits unquoted ints. Note that switching to native Number would lose precision and is the wrong fix.",
+      "files": [],
+      "expectations": [
+        "Shows passing custom { parse, stringify } via the json config option on createClient.",
+        "Notes the >= 1.14.0 client requirement for the json option.",
+        "Mentions output_format_json_quote_64bit_integers: 0 (default since 25.8) so 64-bit integers come back unquoted and parseable as BigInt.",
+        "Warns that switching to native Number would lose precision and is the wrong fix."
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,103 @@
+# Async Inserts
+
+> **Applies to:** all client versions; the relevant settings are server-side.
+> See https://clickhouse.com/docs/en/optimize/asynchronous-inserts.
+
+Backing example:
+[`examples/node/coding/async_insert.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/async_insert.ts).
+
+> **When to use async inserts:** when many small inserts arrive concurrently
+> (e.g., one per HTTP request) and you don't want to maintain a client-side
+> batching layer. ClickHouse will batch them server-side. This is also the
+> recommended ingestion pattern for **ClickHouse Cloud**.
+
+> **When _not_ to use async inserts:** when you already build large batches
+> client-side (e.g., from a stream). Plain inserts are simpler and lower
+> latency. For raw throughput tuning of large async-insert workloads, see
+> [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance).
+
+## Setup
+
+Enable on the client (or per-request) via `clickhouse_settings`:
+
+```ts
+import { createClient, ClickHouseError } from '@clickhouse/client'
+
+const client = createClient({
+  url: process.env.CLICKHOUSE_URL,
+  password: process.env.CLICKHOUSE_PASSWORD,
+  max_open_connections: 10,
+  clickhouse_settings: {
+    async_insert: 1,
+    wait_for_async_insert: 1, // wait for ack from server
+    async_insert_max_data_size: '1000000',
+    async_insert_busy_timeout_ms: 1000,
+  },
+})
+```
+
+## Concurrent small inserts
+
+Each call still uses the client's normal `insert()` API — the server merges
+the batches.
+
+```ts
+const promises = [...new Array(10)].map(async () => {
+  const values = [...new Array(1000).keys()].map(() => ({
+    id: Math.floor(Math.random() * 100_000) + 1,
+    data: Math.random().toString(36).slice(2),
+  }))
+
+  await client
+    .insert({ table: 'async_insert_example', values, format: 'JSONEachRow' })
+    .catch((err) => {
+      if (err instanceof ClickHouseError) {
+        // err.code matches a row in system.errors
+        console.error(`ClickHouse error ${err.code}:`, err)
+        return
+      }
+      console.error('Insert failed:', err)
+    })
+})
+
+await Promise.all(promises)
+```
+
+## `wait_for_async_insert` — fire-and-forget vs ack
+
+| `wait_for_async_insert` | Promise resolves when…                            | Trade-off                                                           |
+| ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
+| `1` (default)           | Server has flushed the batch to the table         | Slower per call; insert errors surface to the client                |
+| `0`                     | Server accepted the row into its in-memory buffer | Faster; flush errors won't surface — only validation/parsing errors |
+
+With `wait_for_async_insert: 1`, expect each insert call to take roughly
+`async_insert_busy_timeout_ms` to resolve when traffic is light, because the
+server waits for more rows or for the timer to fire before flushing.
+
+## Combining DDL with async inserts
+
+When creating tables in scripts that immediately insert, ack the DDL with
+`wait_end_of_query: 1` so the table is ready before the first insert:
+
+```ts
+await client.command({
+  query: `
+    CREATE OR REPLACE TABLE async_insert_example (id Int32, data String)
+    ENGINE MergeTree ORDER BY id
+  `,
+  clickhouse_settings: { wait_end_of_query: 1 },
+})
+```
+
+## Common pitfalls
+
+- **Setting `async_insert` per call but expecting client-side batching.**
+  The client still issues each `insert()` as a separate HTTP request — the
+  batching happens on the server.
+- **Confusing `wait_for_async_insert` (async-insert ack) with
+  `wait_end_of_query` (DDL ack).** They are unrelated.
+- **Treating a resolved insert under `wait_for_async_insert: 0` as
+  durably written.** It only means the server accepted the bytes; flush
+  failures will not surface to the client.
+- **Not handling `ClickHouseError`.** It exposes `err.code`, which maps to
+  rows in the `system.errors` table — use it to decide whether to retry.

package/skills/clickhouse-js-node-coding/reference/client-configuration.md

@@ -0,0 +1,159 @@
+# Client Configuration
+
+> **Applies to:** all versions, with these notable additions:
+>
+> - `pathname` config option: client `>= 1.0.0`.
+> - `clickhouse_setting_*` / `ch_*` URL parameters: client `>= 1.0.0`.
+> - `keep_alive.idle_socket_ttl` (Node-only): client `>= 1.0.0`.
+
+Backing examples:
+[`examples/node/coding/url_configuration.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/url_configuration.ts),
+[`examples/node/coding/clickhouse_settings.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/clickhouse_settings.ts),
+[`examples/node/coding/default_format_setting.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/default_format_setting.ts).
+
+## Answer checklist
+
+When answering configuration questions, include the relevant points:
+
+- Show `createClient` from `@clickhouse/client` with explicit fields when the
+  user is writing code; this is easier to read and review than encoding
+  everything into a URL string.
+- When mentioning the URL form for environment variables / DSNs: show a **Bash**
+  `export` with the literal URL value, and `createClient({ url: process.env.CLICKHOUSE_URL })`
+  in the Node code. **Never construct a URL in application code** — no string
+  concatenation, no template literals, no query-string builders.
+- If URL parameters and object fields both set the same option, URL parameters
+  override the rest of the configuration object.
+- If `clickhouse_settings` appear on `createClient`, explain that they are
+  defaults for every request and can be overridden on individual `query()`,
+  `insert()`, `command()`, or `exec()` calls.
+- Remind long-running services to close the client during graceful shutdown.
+- The `application` field sets the name that appears in `system.query_log`.
+  Do **not** mention any specific HTTP header name — the client handles header
+  mapping internally and the header names are an implementation detail.
+
+## Minimal client
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: process.env.CLICKHOUSE_URL, // defaults to 'http://localhost:8123'
+  username: process.env.CLICKHOUSE_USER, // defaults to 'default'
+  password: process.env.CLICKHOUSE_PASSWORD, // defaults to ''
+  database: 'analytics', // defaults to 'default'
+})
+// ... your queries ...
+await client.close()
+```
+
+`url` accepts a string or a `URL` object. The accepted string format is:
+
+```
+http[s]://[username:password@]hostname:port[/database][?param1=value1&param2=value2]
+```
+
+## Configuration via URL parameters
+
+A fixed allowlist of config fields can be set as URL query parameters
+(plus any key prefixed with `clickhouse_setting_` / `ch_` / `http_header_`).
+**Supported URL parameters override the corresponding values in the rest of
+the configuration object** — when they do, the client logs a warning.
+Unknown URL parameters cause `createClient` to throw
+`Unknown URL parameters: ...`
+(see [`packages/client-common/src/config.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-common/src/config.ts) for the shared allowlist, and [`packages/client-node/src/config.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-node/src/config.ts) for Node-specific URL parameters).
+
+Supported non-prefixed keys parsed by `client-common`: `application`,
+`session_id`, `pathname`, `access_token`, `request_timeout`,
+`max_open_connections`, `compression_request`, `compression_response`,
+`log_level`, `keep_alive_enabled`. Additionally, Node supports
+`keep_alive_idle_socket_ttl` via the Node-specific config implementation.
+Anything else must be passed via the config object on `createClient`.
+
+Prefer explicit object fields in application code. Use the URL form when the
+application receives one connection string from an environment variable, secret
+manager, or config file. The URL value belongs in the environment, not in the
+source code — show it as a shell export and read it in Node:
+
+```bash
+# In your shell environment / deployment config (e.g. .env, Kubernetes secret):
+export CLICKHOUSE_URL='https://bob:secret@my.host:8124/analytics?application=my_analytics_app&ch_async_insert=1&ch_wait_for_async_insert=0'
+```
+
+```ts
+// In your Node.js code — no URL construction needed:
+const client = createClient({ url: process.env.CLICKHOUSE_URL })
+```
+
+The same connection can also be expressed as an explicit config object (useful when you want to document each field individually):
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+createClient({
+  url: 'https://my.host:8124',
+  username: 'bob',
+  password: 'secret',
+  database: 'analytics',
+  application: 'my_analytics_app',
+  clickhouse_settings: { async_insert: 1, wait_for_async_insert: 0 },
+})
+```
+
+## Per-client vs per-request `clickhouse_settings` ⭐
+
+> **Always mention this when discussing `clickhouse_settings`:** settings set
+> on `createClient` are defaults; any individual call can override them.
+
+Settings on `createClient` apply to every request. Settings on a single
+operation (`query`, `insert`, `command`, `exec`) override the client defaults
+for **that call only**.
+
+```ts
+const client = createClient({
+  clickhouse_settings: {
+    date_time_input_format: 'best_effort', // applied to every request
+  },
+})
+
+const rows = await client.query({
+  query: 'SELECT number FROM system.numbers LIMIT 2',
+  format: 'JSONEachRow',
+  clickhouse_settings: {
+    output_format_json_quote_64bit_integers: 1, // overrides client default for this call
+  },
+})
+```
+
+## `default_format` for `exec()`
+
+`client.exec()` runs an arbitrary statement and returns a stream. If your
+query has no trailing `FORMAT …` clause, set `default_format` so the server
+knows what to send back, then wrap the response in a `ResultSet`:
+
+```ts
+import { createClient, ResultSet } from '@clickhouse/client'
+
+const client = createClient()
+const format = 'JSONCompactEachRowWithNamesAndTypes'
+const { stream, query_id } = await client.exec({
+  query: 'SELECT database, name, engine FROM system.tables LIMIT 5',
+  clickhouse_settings: { default_format: format },
+})
+const rs = new ResultSet(stream, format, query_id)
+console.log(await rs.json())
+await client.close()
+```
+
+For ordinary `SELECT`s prefer `client.query({ format })` — `default_format` is
+only needed for raw `exec()`.
+
+## Common pitfalls
+
+- **Don't put a path in `url` and expect it to be the database name when
+  you're behind a proxy.** Use `pathname` for the proxy path and `database`
+  for the DB. (Symptom: "wrong database selected.") See the
+  troubleshooting skill for diagnosis.
+- **Don't create a client per request.** `createClient` opens a connection
+  pool; share one client across the process and `close()` on shutdown.
+- **`max_open_connections` must be `>= 1`** when set explicitly.