clickhouse-js-node-coding

Name: clickhouse-js-node-coding
Author: ClickHouse

494stars32forks

How to install clickhouse-js-node-coding?

clickhouse/agent-skills/clickhouse-js-node-coding

$npx -y skills add ClickHouse/agent-skills --skill clickhouse-js-node-coding

Installs into the current project.

Summary

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 que

Files · 1

View on GitHub

SKILL.md

1	# ClickHouse Node.js Client — Coding
2
3	Reference: https://clickhouse.com/docs/integrations/javascript
4
5	> ⚠️ Node.js runtime only. This skill covers the `@clickhouse/client`
6	> package running in a Node.js runtime exclusively — including **Next.js
7	> Node runtime** API routes, React Server Components, Server Actions, and
8	> standard Node.js processes. Do not apply this skill to browser client
9	> components, Web Workers, Next.js Edge runtime, Cloudflare Workers, or
10	> any usage of `@clickhouse/client-web`. For browser/edge environments, the
11	> correct package is `@clickhouse/client-web`.
12
13	---
14
15	## How to Use This Skill
16
17	1. Match the user's intent to a row in the Task Index below and read the
18	corresponding reference file before writing code. After reading it, scan any
19	Answer checklist in that reference and make sure the final answer covers
20	each relevant item; those checklists capture details users usually need but
21	are easy to omit in short answers.
22	2. Always import from `@clickhouse/client` (never `@clickhouse/client-web`)
23	and create a client with `createClient({ url })` or rely on
24	supported defaults when appropriate. Close it with `await client.close()`
25	preferably when it's no longer needed or during graceful shutdown for global resources.
26	3. Prefer `JSONEachRow` for typical row inserts/selects unless the user
27	has already chosen another format or is streaming raw bytes (CSV / TSV /
28	Parquet — see `examples/node/performance/`).
29	Note on `clickhouse_settings`: settings passed to `createClient` are
30	defaults for every request; they can be overridden per-call by passing
31	`clickhouse_settings` directly to `insert()`, `query()`, or `command()`.
32	Always mention this when the user configures settings at the client level.
33	4. Always use `query_params` for user-supplied values — never template-
34	literal-interpolate them into SQL. See `reference/query-parameters.md`.
35	**When answering a parameter-binding question, your response must
36	explicitly name template-literal interpolation as a "SQL injection
37	risk"** — even when the user only asked about syntax and did not raise
38	security. The literal phrase "SQL injection" needs to appear; this is
39	the most common mistake from PostgreSQL/MySQL users and the security
40	framing is part of the correct answer, not an optional aside.
41	5. Pick the right method for the job:
42	- `client.insert()` — write rows.
43	- `client.query()` + `resultSet.json()` / `.text()` / `.stream()` — read
44	rows that return data.
45	- `client.command()` — DDL and other statements that don't return rows
46	(`CREATE`, `DROP`, `TRUNCATE`, `ALTER`, `SET` in a session, etc.).
47	- `client.exec()` — when you need the raw response stream of an arbitrary
48	statement (rare in coding scenarios).
49	- `client.ping()` — health check; returns `{ success, error? }`, never
50	throws on connection failure.
51	6. Note version constraints when relevant. Examples:
52	- `pathname` config option: client `>= 1.0.0`.
53	- `BigInt` values in `query_params`: client `>= 1.15.0`.
54	- `TupleParam` and JS `Map` in `query_params`: client `>= 1.9.0`.
55	- Configurable `json.parse` / `json.stringify`: client `>= 1.14.0`.
56	- `Time` / `Time64` data types: ClickHouse server `>= 25.6`.
57	- `QBit` data type: ClickHouse server `>= 25.10` (GA on `26.x`).
58	- `Dynamic` / `Variant` / new `JSON` types: ClickHouse server `>= 24.1` /
59	`24.5` / `24.8` (no longer experimental since `25.3`).
60
61	---
62
63	## Task Index
64
65	Identify the user's task and read the matching reference file.
66
67	\| Task \| Triggers / symptoms \| Reference file \|
68	\| -------------------------------------------------------- \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \| ----------------------------------- \|
69	\| Configure / connect the client \| Building a `createClient` call, URL parameters, `clickhouse_settings`, default format, custom HTTP headers

People who liked this also viewed

6 picks

Type

clickhouse-js-node-coding

494stars32forks

View on GitHub

How to install clickhouse-js-node-coding?

clickhouse/agent-skills/clickhouse-js-node-coding

$npx -y skills add ClickHouse/agent-skills --skill clickhouse-js-node-coding

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# ClickHouse Node.js Client — Coding
2
3	Reference: https://clickhouse.com/docs/integrations/javascript
4
5	> ⚠️ Node.js runtime only. This skill covers the `@clickhouse/client`
6	> package running in a Node.js runtime exclusively — including **Next.js
7	> Node runtime** API routes, React Server Components, Server Actions, and
8	> standard Node.js processes. Do not apply this skill to browser client
9	> components, Web Workers, Next.js Edge runtime, Cloudflare Workers, or
10	> any usage of `@clickhouse/client-web`. For browser/edge environments, the
11	> correct package is `@clickhouse/client-web`.
12
13	---
14
15	## How to Use This Skill
16
17	1. Match the user's intent to a row in the Task Index below and read the
18	corresponding reference file before writing code. After reading it, scan any
19	Answer checklist in that reference and make sure the final answer covers
20	each relevant item; those checklists capture details users usually need but
21	are easy to omit in short answers.
22	2. Always import from `@clickhouse/client` (never `@clickhouse/client-web`)
23	and create a client with `createClient({ url })` or rely on
24	supported defaults when appropriate. Close it with `await client.close()`
25	preferably when it's no longer needed or during graceful shutdown for global resources.
26	3. Prefer `JSONEachRow` for typical row inserts/selects unless the user
27	has already chosen another format or is streaming raw bytes (CSV / TSV /
28	Parquet — see `examples/node/performance/`).
29	Note on `clickhouse_settings`: settings passed to `createClient` are
30	defaults for every request; they can be overridden per-call by passing
31	`clickhouse_settings` directly to `insert()`, `query()`, or `command()`.
32	Always mention this when the user configures settings at the client level.
33	4. Always use `query_params` for user-supplied values — never template-
34	literal-interpolate them into SQL. See `reference/query-parameters.md`.
35	**When answering a parameter-binding question, your response must
36	explicitly name template-literal interpolation as a "SQL injection
37	risk"** — even when the user only asked about syntax and did not raise
38	security. The literal phrase "SQL injection" needs to appear; this is
39	the most common mistake from PostgreSQL/MySQL users and the security
40	framing is part of the correct answer, not an optional aside.
41	5. Pick the right method for the job:
42	- `client.insert()` — write rows.
43	- `client.query()` + `resultSet.json()` / `.text()` / `.stream()` — read
44	rows that return data.
45	- `client.command()` — DDL and other statements that don't return rows
46	(`CREATE`, `DROP`, `TRUNCATE`, `ALTER`, `SET` in a session, etc.).
47	- `client.exec()` — when you need the raw response stream of an arbitrary
48	statement (rare in coding scenarios).
49	- `client.ping()` — health check; returns `{ success, error? }`, never
50	throws on connection failure.
51	6. Note version constraints when relevant. Examples:
52	- `pathname` config option: client `>= 1.0.0`.
53	- `BigInt` values in `query_params`: client `>= 1.15.0`.
54	- `TupleParam` and JS `Map` in `query_params`: client `>= 1.9.0`.
55	- Configurable `json.parse` / `json.stringify`: client `>= 1.14.0`.
56	- `Time` / `Time64` data types: ClickHouse server `>= 25.6`.
57	- `QBit` data type: ClickHouse server `>= 25.10` (GA on `26.x`).
58	- `Dynamic` / `Variant` / new `JSON` types: ClickHouse server `>= 24.1` /
59	`24.5` / `24.8` (no longer experimental since `25.3`).
60
61	---
62
63	## Task Index
64
65	Identify the user's task and read the matching reference file.
66
67	\| Task \| Triggers / symptoms \| Reference file \|
68	\| -------------------------------------------------------- \| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \| ----------------------------------- \|
69	\| Configure / connect the client \| Building a `createClient` call, URL parameters, `clickhouse_settings`, default format, custom HTTP headers

People who liked this also viewed

6 picks

Type