clickhouse-js-node-coding

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 26841bf3d95f · 24 Oct 2026Report an issue or request a re-scan

• Publisherclickhouse GitHub organizationOwner of the repository this skill is read from
• Source folderclickhouse/agent-skills/skills/clickhouse-js-node-codingThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict26841bf3d95fA new audit runs when the source changes
• Repository statusNot archivedLast push 3 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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 or
  customizing JSON parsing. Do NOT use for browser/Web client code.
---

# 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 client with `createClient({ url })` or rely on
   supported defaults when appropriate. Close it with `await client.close()`
   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/`).
   **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`.
   **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
     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`.
   - `QBit` data type: ClickHouse server `>= 25.10` (GA on `26.x`).
   - `Dynamic` / `Variant` / new `JSON` types: ClickHouse server `>= 24.1` /
     `24.5` / `24.8` (no longer experimental since `25.3`).

---

## 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` |
| **Compress requests / responses**                        | `compression`, gzip vs `zstd`, `{ codec }` option shape, Node version requirements, web limitations                                                                                                                             | `reference/compression.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`                                                                                                                           

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/clickhouse/agent-skills
git -C agent-skills checkout 26841bf3d95f

Works in

1. 2026-10-24
   ✓SAFE B 89 / 100

   first audit · source 26841bf3d95f

Questions about clickhouse-js-node-coding

• github.com/clickhouse/agent-skills/tree/main/skills/clickhouse-j — the audited source at commit 26841bf3d95f and every finding aboveObserved · 24 Oct 2026

Spotted something wrong? Report a correction · Methodology