@clickhouse/client 1.18.5 → 1.19.0

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export { type NodeClickHouseClientConfigOptions as ClickHouseClientConfigOptions
 export { ResultSet, type StreamReadable } from './result_set';
 export { drainStream } from './connection/stream';
 /** Re-export @clickhouse/client-common types */
-export { type BaseClickHouseClientConfigOptions, type BaseQueryParams, type QueryParams, type ExecParams, type InsertParams, type InsertValues, type CommandParams, type CommandResult, type ExecResult, type InsertResult, type DataFormat, type RawDataFormat, type JSONDataFormat, type StreamableDataFormat, type StreamableJSONDataFormat, type SingleDocumentJSONFormat, type Logger, type LogParams, type ErrorLogParams, type WarnLogParams, type ClickHouseSettings, type MergeTreeSettings, type Row, type ResponseJSON, type InputJSON, type InputJSONObjectEachRow, type BaseResultSet, type PingResult, ClickHouseError, parseError, ClickHouseLogLevel, SettingsMap, SupportedJSONFormats, SupportedRawFormats, StreamableFormats, StreamableJSONFormats, SingleDocumentJSONFormats, RecordsJSONFormats, type SimpleColumnType, type ParsedColumnSimple, type ParsedColumnEnum, type ParsedColumnFixedString, type ParsedColumnNullable, type ParsedColumnDecimal, type ParsedColumnDateTime, type ParsedColumnDateTime64, type ParsedColumnArray, type ParsedColumnTuple, type ParsedColumnMap, type ParsedColumnType, parseColumnType, SimpleColumnTypes, type ProgressRow, isProgressRow, isRow, isException, type RowOrProgress, type ClickHouseAuth, type ClickHouseJWTAuth, type ClickHouseCredentialsAuth, TupleParam, } from '@clickhouse/client-common';
+export { type BaseClickHouseClientConfigOptions, type BaseQueryParams, type QueryParams, type ExecParams, type InsertParams, type InsertValues, type CommandParams, type CommandResult, type ExecResult, type InsertResult, type DataFormat, type RawDataFormat, type JSONDataFormat, type StreamableDataFormat, type StreamableJSONDataFormat, type SingleDocumentJSONFormat, type Logger, type LogParams, type ErrorLogParams, type WarnLogParams, type ClickHouseSettings, type MergeTreeSettings, type Row, type ResponseJSON, type InputJSON, type InputJSONObjectEachRow, type BaseResultSet, type PingResult, type ResponseHeaders, ClickHouseError, parseError, ClickHouseLogLevel, SettingsMap, SupportedJSONFormats, SupportedRawFormats, StreamableFormats, StreamableJSONFormats, SingleDocumentJSONFormats, RecordsJSONFormats, type SimpleColumnType, type ParsedColumnSimple, type ParsedColumnEnum, type ParsedColumnFixedString, type ParsedColumnNullable, type ParsedColumnDecimal, type ParsedColumnDateTime, type ParsedColumnDateTime64, type ParsedColumnArray, type ParsedColumnTuple, type ParsedColumnMap, type ParsedColumnType, parseColumnType, SimpleColumnTypes, type ProgressRow, isProgressRow, isRow, isException, type RowOrProgress, type ClickHouseAuth, type ClickHouseJWTAuth, type ClickHouseCredentialsAuth, TupleParam, } from '@clickhouse/client-common';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAGiB;AAFf,0GAAA,oBAAoB,OAAoB;AAG1C,mCAAuC;AAA9B,sGAAA,YAAY,OAAA;AAErB,2CAA6D;AAApD,uGAAA,SAAS,OAAA;AAClB,8CAAiD;AAAxC,qGAAA,WAAW,OAAA;AAEpB,gDAAgD;AAChD,2DA8DkC;AAjChC,gHAAA,eAAe,OAAA;AACf,2GAAA,UAAU,OAAA;AACV,mHAAA,kBAAkB,OAAA;AAClB,4GAAA,WAAW,OAAA;AACX,qHAAA,oBAAoB,OAAA;AACpB,oHAAA,mBAAmB,OAAA;AACnB,kHAAA,iBAAiB,OAAA;AACjB,sHAAA,qBAAqB,OAAA;AACrB,0HAAA,yBAAyB,OAAA;AACzB,mHAAA,kBAAkB,OAAA;AAalB,gHAAA,eAAe,OAAA;AACf,kHAAA,iBAAiB,OAAA;AAEjB,8GAAA,aAAa,OAAA;AACb,sGAAA,KAAK,OAAA;AACL,4GAAA,WAAW,OAAA;AAKX,2GAAA,UAAU,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAGiB;AAFf,0GAAA,oBAAoB,OAAoB;AAG1C,mCAAuC;AAA9B,sGAAA,YAAY,OAAA;AAErB,2CAA6D;AAApD,uGAAA,SAAS,OAAA;AAClB,8CAAiD;AAAxC,qGAAA,WAAW,OAAA;AAEpB,gDAAgD;AAChD,2DA+DkC;AAjChC,gHAAA,eAAe,OAAA;AACf,2GAAA,UAAU,OAAA;AACV,mHAAA,kBAAkB,OAAA;AAClB,4GAAA,WAAW,OAAA;AACX,qHAAA,oBAAoB,OAAA;AACpB,oHAAA,mBAAmB,OAAA;AACnB,kHAAA,iBAAiB,OAAA;AACjB,sHAAA,qBAAqB,OAAA;AACrB,0HAAA,yBAAyB,OAAA;AACzB,mHAAA,kBAAkB,OAAA;AAalB,gHAAA,eAAe,OAAA;AACf,kHAAA,iBAAiB,OAAA;AAEjB,8GAAA,aAAa,OAAA;AACb,sGAAA,KAAK,OAAA;AACL,4GAAA,WAAW,OAAA;AAKX,2GAAA,UAAU,OAAA"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "1.18.5";
+declare const _default: "1.19.0";
 export default _default;

package/dist/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = '1.18.5';
+exports.default = '1.19.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -2,7 +2,7 @@
   "name": "@clickhouse/client",
   "description": "Official JS client for ClickHouse DB - Node.js implementation",
   "homepage": "https://clickhouse.com",
-  "version": "1.18.5",
+  "version": "1.19.0",
   "license": "Apache-2.0",
   "keywords": [
     "clickhouse",
@@ -44,7 +44,7 @@
     "build": "rm -rf dist; tsc"
   },
   "dependencies": {
-    "@clickhouse/client-common": "1.18.5"
+    "@clickhouse/client-common": "1.19.0"
   },
   "devDependencies": {
     "simdjson": "^0.9.2"

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

@@ -5,14 +5,8 @@ description: >
   (`@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).
+  managing sessions and temporary tables, working with data types or
+  customizing JSON parsing. Do NOT use for browser/Web client code.
 ---
 
 # ClickHouse Node.js Client — Coding
@@ -37,9 +31,9 @@ Reference: https://clickhouse.com/docs/integrations/javascript
    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
+   and create a client with `createClient({ url })` or rely on
    supported defaults when appropriate. Close it with `await client.close()`
-   during graceful shutdown.
+   preferably when it's no longer needed or during graceful shutdown for global resources.
 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/`).
@@ -49,6 +43,12 @@ Reference: https://clickhouse.com/docs/integrations/javascript
    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`.
+   **When answering a parameter-binding question, your response must
+   explicitly name template-literal interpolation as a "SQL injection
+   risk"** — even when the user only asked about syntax and did not raise
+   security. The literal phrase "SQL injection" needs to appear; this is
+   the most common mistake from PostgreSQL/MySQL users and the security
+   framing is part of the correct answer, not an optional aside.
 5. **Pick the right method for the job:**
    - `client.insert()` — write rows.
    - `client.query()` + `resultSet.json()` / `.text()` / `.stream()` — read
@@ -67,10 +67,6 @@ Reference: https://clickhouse.com/docs/integrations/javascript
    - `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.
 
 ---
 
@@ -97,16 +93,13 @@ Identify the user's task and read the matching reference file.
 ## 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'`).
+  Web).
 - 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/`.
+  small / medium result sets; for bigger results suggest streaming.
 - 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

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

@@ -3,9 +3,6 @@
 > **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
@@ -13,12 +10,11 @@ Backing example:
 
 > **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).
+> latency.
 
 ## Setup
 
-Enable on the client (or per-request) via `clickhouse_settings`:
+Enable on the client level or per-request via `clickhouse_settings`:
 
 ```ts
 import { createClient, ClickHouseError } from '@clickhouse/client'
@@ -89,6 +85,9 @@ await client.command({
 })
 ```
 
+Even better is to create a specialized client for inserts with the appropriate async
+settings and a separate client for DDL and other queries.
+
 ## Common pitfalls
 
 - **Setting `async_insert` per call but expecting client-side batching.**
@@ -101,3 +100,8 @@ await client.command({
   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.
+
+## See also
+
+- For raw throughput tuning of large async-insert workloads,
+  see [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance).

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

@@ -6,11 +6,6 @@
 > - `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:
@@ -53,22 +48,7 @@ await client.close()
 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`.
+## Configuration via URL
 
 Prefer explicit object fields in application code. Use the URL form when the
 application receives one connection string from an environment variable, secret
@@ -77,7 +57,7 @@ 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'
+export CLICKHOUSE_URL='https://bob:secret@my.host:8124/analytics'
 ```
 
 ```ts
@@ -85,21 +65,6 @@ export CLICKHOUSE_URL='https://bob:secret@my.host:8124/analytics?application=my_
 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
@@ -112,13 +77,12 @@ for **that call only**.
 ```ts
 const client = createClient({
   clickhouse_settings: {
-    date_time_input_format: 'best_effort', // applied to every request
+    output_format_json_quote_64bit_integers: 0, // applied to every request
   },
 })
 
 const rows = await client.query({
-  query: 'SELECT number FROM system.numbers LIMIT 2',
-  format: 'JSONEachRow',
+  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
   },
@@ -155,5 +119,5 @@ only needed for raw `exec()`.
   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.
+  pool; share one client across requests and `close()` on shutdown.
 - **`max_open_connections` must be `>= 1`** when set explicitly.

package/skills/clickhouse-js-node-coding/reference/custom-json.md

@@ -3,9 +3,6 @@
 > **Requires:** client `>= 1.14.0` (configurable `json.parse` and
 > `json.stringify`). Earlier versions cannot swap the JSON implementation.
 
-Backing example:
-[`examples/node/coding/custom_json_handling.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/custom_json_handling.ts).
-
 ## Answer checklist
 
 When the user wants `UInt64`/`Int64` values back as `BigInt`:
@@ -66,7 +63,7 @@ const valueSerializer = (value: unknown): unknown => {
 
 const client = createClient({
   json: {
-    parse: JSON.parse,
+    parse: JSON.parse, // use default parsing
     stringify: (obj: unknown) => JSON.stringify(valueSerializer(obj)),
   },
 })
@@ -85,17 +82,12 @@ await client.insert({
   format: 'JSONEachRow',
   values: [
     {
-      id: BigInt(250000000000000200), // serialized as a string
+      id: BigInt('250000000000000200'), // serialized as a string
       dt: new Date(), // serialized as ms since epoch
     },
   ],
 })
 
-const rows = await client.query({
-  query: 'SELECT * FROM inserts_custom_json_handling',
-  format: 'JSONEachRow',
-})
-console.info(await rows.json())
 await client.close()
 ```
 
@@ -126,16 +118,65 @@ const client = createClient({
 })
 ```
 
-This applies to **both** outgoing JSON bodies and incoming JSON-format
-responses. Combine with `output_format_json_quote_64bit_integers: 0` (the
-default since CH 25.8) so the server emits unquoted 64-bit integers that
-`json-bigint` can parse to `BigInt`.
+`output_format_json_quote_64bit_integers: 0` is the default since
+ClickHouse `25.8`; setting it explicitly is useful for older servers and
+makes the example self-contained. With it off, the server emits unquoted
+64-bit integers that `json-bigint` parses straight to `BigInt`. The
+`json` option applies to **both** outgoing JSON bodies and incoming
+JSON-format responses.
+
+## Recipe: Zero-dep BigInt parsing (no `npm install`)
+
+If adding a dependency is awkward (locked lockfile, restricted environment,
+or you just don't want to pull in `json-bigint`), you can plug in a
+hand-rolled reviver. This uses the `context.source` argument that
+`JSON.parse` revivers gained in Node `>= 20.16` / `>= 21.7`, so the raw
+numeric literal is available before it's coerced to a JS `number`:
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+const parseBigInt = (text: string) =>
+  JSON.parse(text, function (key, value, context) {
+    if (key.endsWith('__bigint')) {
+      return BigInt(context.source)
+    }
+    return value
+  })
+
+const client = createClient({
+  json: {
+    parse: parseBigInt,
+    stringify: JSON.stringify, // use default stringify
+  },
+  clickhouse_settings: { output_format_json_quote_64bit_integers: 0 },
+})
+
+const rs = await client.query({
+  query: 'SELECT toUInt64(250000000000000200) AS id__bigint',
+})
+const { data } = await rs.json()
+console.log(data[0].id__bigint) // 250000000000000200
+
+await client.close()
+```
+
+Trade-offs versus `json-bigint`:
+
+- ✓ No new dependency to install.
+- ✓ Only promotes known to be 64-bit integers to `BigInt`.
+- ✗ Requires Node `>= 20.16` / `>= 21.7` for the reviver `context.source`.
+  On older Node, prefer `json-bigint` or upgrade Node.
+- ✗ Outgoing `stringify` still uses default `JSON.stringify`, which throws
+  on `BigInt`. Pair with the `valueSerializer` pattern above if your
+  inserts contain `BigInt` values.
 
 ## Common pitfalls
 
 - **Setting `json.parse` only.** That only affects reading JSON responses;
   outgoing JSON bodies use `json.stringify`. If you want consistent custom
-  handling in both directions, generally provide a matching `stringify` too.
+  handling in both directions, generally provide a matching `stringify` too
+  or a throwing serializer that prevents mismatches.
 - **Forgetting `bigint` handling in `stringify`.** Default `JSON.stringify`
   throws on `BigInt`; if your data ever contains one, the insert will fail
   with `TypeError: Do not know how to serialize a BigInt`.
@@ -147,3 +188,6 @@ default since CH 25.8) so the server emits unquoted 64-bit integers that
   are silently rounded. Do **not** try to fix precision loss by calling
   `Number()`, `parseInt()`, or `parseFloat()` on the value. The correct fix
   is a `BigInt`-aware parser (shown above), not a lossy cast.
+- **Mixing BigInt and number for the same column.** If some values are `BigInt` and
+  others are `number`, your app code needs to handle both types. Otherwise
+  JavaScript will throw a `TypeError: Cannot mix BigInt and other types`.

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

@@ -10,10 +10,6 @@
 > - `Time` / `Time64`: ClickHouse `>= 25.6` and require
 >   `enable_time_time64_type: 1`.
 
-Backing examples:
-[`examples/node/coding/dynamic_variant_json.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/dynamic_variant_json.ts),
-[`examples/node/coding/time_time64.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/time_time64.ts).
-
 ## Answer checklist
 
 When answering about storing and reading JSON objects:
@@ -21,6 +17,29 @@ When answering about storing and reading JSON objects:
 - Use the new `JSON` column type, introduced in ClickHouse `>= 24.8`.
 - Say `JSON` is no longer experimental since ClickHouse `25.3`; on older
   supported versions, enable `allow_experimental_json_type`.
+- **State the version policy in your explanation AND inline in the code.**
+  When you set `allow_experimental_json_type` (or any `allow_experimental_*_type`)
+  in code, you must do BOTH of the following:
+  1. Put an inline comment directly above the setting that names the version
+     where the type was introduced and the version where it became
+     non-experimental. The comment is the durable version provenance — it
+     lives in the user's source file long after the chat reply is gone.
+  2. Repeat the version policy in your prose reply.
+
+  For the `JSON` column type the inline comment must look like:
+
+  ```ts
+  clickhouse_settings: {
+    // JSON type introduced in ClickHouse 24.8, non-experimental since 25.3.
+    // This setting is required only on 24.8–25.2; harmless on >= 25.3.
+    allow_experimental_json_type: 1,
+  }
+  ```
+
+  Without the inline comment, a reader on a newer server has no idea the
+  setting is a no-op and a reader on an older server has no idea why it's
+  required.
+
 - Insert real JS objects with `format: 'JSONEachRow'`; do not
   `JSON.stringify()` the column value.
 - Read with a JSON output format such as `JSONEachRow` and `resultSet.json()`;
@@ -32,8 +51,10 @@ When answering about storing and reading JSON objects:
 import { createClient } from '@clickhouse/client'
 
 const client = createClient({
-  // Required only on ClickHouse < 25.3 — harmless to leave on
   clickhouse_settings: {
+    // Variant introduced in 24.1, Dynamic in 24.5, JSON in 24.8.
+    // All three are non-experimental since 25.3; these settings are
+    // required only on 24.1–25.2 and are harmless on >= 25.3.
     allow_experimental_variant_type: 1,
     allow_experimental_dynamic_type: 1,
     allow_experimental_json_type: 1,
@@ -77,6 +98,33 @@ const rs = await client.query({
 console.log(await rs.json())
 ```
 
+Outputs:
+
+```js
+;[
+  {
+    id: '1',
+    var: '42',
+    dynamic: 'foo',
+    json: { foo: 'x' },
+    'variantType(var)': 'Int64',
+    'dynamicType(dynamic)': 'String',
+    'dynamicType(json.foo)': 'String',
+    'dynamicType(json.bar)': 'None',
+  },
+  {
+    id: '2',
+    var: 'str',
+    dynamic: '144',
+    json: { bar: '10' },
+    'variantType(var)': 'String',
+    'dynamicType(dynamic)': 'Int64',
+    'dynamicType(json.foo)': 'None',
+    'dynamicType(json.bar)': 'Int64',
+  },
+]
+```
+
 ### Notes
 
 - The `JSON` column type accepts a real JS object on insert and returns one
@@ -154,7 +202,8 @@ await client.insert({
 - Pass values as **strings** in the `HH:MM:SS[.fraction]` format. Negatives
   are supported; the magnitude can exceed 24 hours.
 - For `Time64(p)` with `p > 3`, do not use JS `Date` — it tops out at
-  millisecond precision and will silently truncate.
+  millisecond precision and will silently truncate. Store nanosecond values
+  separately and provide on stringify as needed.
 
 ## Common pitfalls
 
@@ -167,3 +216,6 @@ await client.insert({
 - **Reading a `Variant`/`Dynamic` value of type `Int64` and being surprised
   it's a string.** That's the standard 64-bit-integers-in-JSON behavior;
   see the troubleshooting skill if you need to change it.
+- **Avoid parsing Variant/Dynamic/JSON columns that mix strings and 64-bit**
+  without checking their returned types first. Otherwise a number stored in
+  a string will come back as a number or vice versa.

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

@@ -3,12 +3,6 @@
 > **Applies to:** all versions. The `columns` option (both forms) and the
 > `database` config field are universally supported.
 
-Backing examples:
-[`examples/node/coding/insert_specific_columns.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_specific_columns.ts),
-[`examples/node/coding/insert_exclude_columns.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_exclude_columns.ts),
-[`examples/node/coding/insert_ephemeral_columns.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_ephemeral_columns.ts),
-[`examples/node/coding/insert_into_different_db.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_into_different_db.ts).
-
 ## Answer checklist
 
 When explaining partial-column inserts:
@@ -29,9 +23,9 @@ get their declared default.
 ```ts
 await client.insert({
   table: 'events',
+  columns: ['message'], // the rest of the events table columns get their DEFAULTs
   format: 'JSONEachRow',
   values: [{ message: 'foo' }],
-  columns: ['message'], // `id` will get its default (0 for UInt32)
 })
 ```
 

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

@@ -4,14 +4,8 @@
 > ClickHouse feature; the JSON _formats_ listed here are universally supported
 > by the client.
 
-Backing examples:
-[`examples/node/coding/array_json_each_row.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/array_json_each_row.ts),
-[`examples/node/coding/insert_data_formats_overview.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_data_formats_overview.ts).
-
 > **Raw / binary formats (CSV, TSV, CustomSeparated, Parquet) require a Node
-> stream as input.** See
-> [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance)
-> — defer if the user wants to insert from a file or `Readable`.
+> stream as input.** Suggest streaming when the user wants to insert from a file or `Readable`.
 
 ## Answer checklist
 
@@ -125,12 +119,12 @@ await client.insert({
 
 ## Quick chooser
 
-| Use case                                     | Format                                            |
-| -------------------------------------------- | ------------------------------------------------- |
-| Insert plain JS objects                      | `JSONEachRow` _(default)_                         |
-| Insert tuples / column-positional rows       | `JSONCompactEachRow`                              |
-| Insert with explicit column ordering / types | `JSONCompactEachRow*WithNames…`                   |
-| Insert a single document with metadata       | `JSON`, `JSONCompact`                             |
+| Use case                                     | Format                                                  |
+| -------------------------------------------- | ------------------------------------------------------- |
+| Insert plain JS objects                      | `JSONEachRow` _(default)_                               |
+| Insert tuples / column-positional rows       | `JSONCompactEachRow`                                    |
+| Insert with explicit column ordering / types | `JSONCompactEachRow*WithNames…`                         |
+| Insert a single document with metadata       | `JSON`, `JSONCompact`                                   |
 | Insert from a CSV / TSV / Parquet file       | Raw format + Node stream → `examples/node/performance/` |
 
 ## Common pitfalls
@@ -143,3 +137,6 @@ await client.insert({
   `JSONColumnsWithMetadata`).
 - For type guidance (`Decimal` strings, `Date` objects, `BigInt`), see
   `insert-values.md` and `custom-json.md`.
+- **Use runtime type checkers like `zod` or `io-ts` if your app ingests untrusted JSON.**
+  It's easier to debug mismatches between your data and the format's expected shape with a validation library used at the place of ingestion than with ClickHouse errors.
+  This is especially true in the middle of a large insert batch or streaming operation.

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

@@ -3,12 +3,6 @@
 > **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
@@ -18,7 +12,7 @@ When the data already lives in ClickHouse, use `client.command()` with a raw
 await client.command({
   query: `
     INSERT INTO target
-    SELECT '42', quantilesBFloat16State(0.5)(arrayJoin([toFloat32(10), toFloat32(20)]))
+    SELECT * FROM source
   `,
 })
 ```
@@ -71,7 +65,7 @@ await client.insert({
   format: 'JSONEachRow',
   values: [{ id: '42', dt: new Date() }],
   clickhouse_settings: {
-    date_time_input_format: 'best_effort',
+    date_time_input_format: 'best_effort', // default on the Cloud
   },
 })
 ```
@@ -81,6 +75,13 @@ await client.insert({
 
 ## Inserting `Decimal*` values
 
+**IMPORTANT:** Make sure that the application code you're working on or the user
+prompt clearly indicates that floats are not used anywhere for decimal values.
+The most common scenario is using floats for money amounts in the app while the
+database uses `Decimal` for them. In that case, the app code should be changed
+to use a proper decimal library and serialization strategy (custom serializer
+or a class using `toJSON()`) to `string` instead of JS `number`.
+
 Decimals must be passed as **strings** in JSON formats to avoid precision
 loss in JavaScript:
 
@@ -130,8 +131,6 @@ const rs = await client.query({
 
 ## 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
@@ -139,3 +138,4 @@ const rs = await client.query({
   ISO-8601 with the `T`/`Z` separators.
 - **Hand-building `VALUES` with user input.** Always parameterize user data;
   see `reference/query-parameters.md`.
+- **Using floats in the app and expect `Decimal` columns to store them safely.** Use a proper decimal library and pass them as strings to avoid precision loss.

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

@@ -1,12 +1,29 @@
 # Ping the Server
 
-> **Applies to:** all versions. `ping()` returns a discriminated
+> **Applies to:** all versions. `ping()` returns a discriminated union
 > `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).
+## Answer checklist
+
+When answering "how do I health-check / readiness-probe ClickHouse?":
+
+- Use `await client.ping()` (or `ping({ select: true })`) and branch on
+  `result.success` directly — **do not** wrap in `try/catch` as the only
+  check, and do not substitute `query('SELECT 1')`.
+- For a readiness probe / "can it serve traffic", recommend
+  `client.ping({ select: true })` so credentials and the query layer are
+  validated, not just the socket.
+- **Always contrast the two forms explicitly in your answer**, even when
+  you're recommending one: plain `client.ping()` hits `/ping` (TCP/HTTP
+  reachability only — does not validate credentials or query processing);
+  `client.ping({ select: true })` issues a lightweight `SELECT 1` (validates
+  auth and query path). Name both and say which to use for liveness vs
+  readiness.
+- Recommend lowering `request_timeout` on the client used for probes so
+  they fail fast instead of hanging on the default timeout — pick a value
+  comparable to the probe interval (e.g., `1500`–`2000` ms for a
+  2-second-interval probe).
 
 ## Successful ping
 
@@ -118,3 +135,7 @@ const r = await client.ping({ select: true })
 - **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.
+- **Only ping the ClickHouse server in your app's liveness probe** if the app
+  has to be restarted to recover from a ClickHouse outage. If the app can recover
+  the connection to ClickHouse without a restart, put the ping in a readiness
+  probe instead so the app doesn't get killed unnecessarily.

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

@@ -6,17 +6,16 @@
 > `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**.
+- **Your response must explicitly name template-literal / string
+  interpolation of user input as a SQL injection risk** — even when the
+  user only asked "how do I bind values" and did not mention security.
+  This is non-negotiable: the security framing is part of the right
+  answer, not an optional aside.
 - 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.).
@@ -42,8 +41,9 @@ 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
+
+// ❌ Dangerous — never do this with user-controlled values
 await client.query({ query: `SELECT * FROM users WHERE id = ${userId}` })
 
 // ✓ Safe — parameterized

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

@@ -4,11 +4,6 @@
 > `>= 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.
@@ -27,6 +22,9 @@ const rows = await client.query({
 })
 const result = await rows.json<Row>() // Row[]
 result.forEach((r) => console.log(r))
+// { number: '0' }
+// { number: '1' }
+// ...
 await client.close()
 ```
 

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

@@ -3,9 +3,30 @@
 > **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).
+## Answer checklist
+
+When answering "temp table disappears between calls" / "how do I share a
+session" / anything involving `session_id`:
+
+- State plainly that **temporary tables and session-scoped state are tied
+  to a `session_id`** — without a stable `session_id` across calls, every
+  request gets a fresh server-side session and the temp table is gone.
+- Set `session_id` via `crypto.randomUUID()` either on `createClient` or
+  per-call.
+- Warn that **`session_id` on a global / module-static client is an
+  anti-pattern** in any concurrent app (Express, server actions, workers,
+  etc.) — concurrent requests will share the same session and trip
+  `"Session is locked by a concurrent client"`. Recommend a short-lived
+  per-workflow client or per-call `session_id` instead.
+- If `session_id` is set on the client, also set `max_open_connections: 1`
+  to serialize calls and avoid the concurrent-session error.
+- For ClickHouse Cloud or any load-balanced deployment: **explicitly
+  recommend replica-aware routing or a single-node hostname** as the
+  primary remedy when sessions are needed. Sessions are pinned to one
+  node; behind an LB, consecutive requests may land on different nodes
+  and the temp table will appear to vanish. "Just collapse the workflow
+  into one handler" or "use a non-temporary table" are valid fallbacks
+  but secondary — name the routing fix first.
 
 ## When you need a session
 
@@ -40,8 +61,8 @@ 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).
+script, a background job, a single user's session that you've already manually
+serialized in the code).
 
 ```ts
 import { createClient } from '@clickhouse/client'
@@ -49,7 +70,7 @@ import * as crypto from 'node:crypto'
 
 const client = createClient({
   session_id: crypto.randomUUID(),
-  max_open_connections: 1, // prevent concurrent-session errors
+  max_open_connections: 1, // safeguard against concurrent-session errors
 })
 
 await client.command({
@@ -81,7 +102,7 @@ import * as crypto from 'node:crypto'
 
 const client = createClient({
   session_id: crypto.randomUUID(),
-  max_open_connections: 1, // prevent concurrent-session errors
+  max_open_connections: 1, // safe-guard against concurrent-session errors
 })
 
 await client.command({
@@ -125,13 +146,18 @@ 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.
+Mitigations (in order of preference):
+
+- **For ClickHouse Cloud, use [replica-aware
+  routing](https://clickhouse.com/docs/manage/replica-aware-routing)** so
+  consecutive requests in the same session land on the same node. This is
+  the right primary fix when you need sessions in a Cloud deployment.
+- Talk to a single node directly (e.g., a node-pinned hostname) when
+  routing isn't an option.
+- As a fallback only: avoid sessions for cross-node workflows and persist
+  intermediate state in a regular (non-temporary) table instead. This
+  trades the session requirement away rather than fixing it — use it only
+  if replica-aware routing / single-node connections aren't available.
 
 ## Common pitfalls
 

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

@@ -1,103 +0,0 @@
-{
-  "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-troubleshooting/evals/evals.json

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