clickhouse-js-node-coding

Files (13)

• SKILL.md
• async-insert.md · reference/
• client-configuration.md · reference/
• compression.md · reference/
• custom-json.md · reference/
• data-types.md · reference/
• insert-columns.md · reference/
• insert-formats.md · reference/
• insert-values.md · reference/
• ping.md · reference/
• query-parameters.md · reference/
• select-formats.md · reference/
• sessions.md · reference/

SKILL.md (first lines)

# 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`                                                                                                                             | `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`; inserting a UUID into a `UInt128` column is tricky — use when the user is writing code that stores a UUID as `UInt128` | `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`, `QBit` (vector search)                                                                                                                                                 | `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).
- Always `await client.close()` at the end of self-contained snippets; in
  long-running services, close on graceful shutdown.
- 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 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
  `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

From ClickHouse/agent-skills, Apache-2.0.

More from ClickHouse/agent-skills