---
name: clickhouse-js-node-coding
description: Reference: https://clickhouse.com/docs/integrations/javascript
---

# clickhouse-js-node-coding

Reference: https://clickhouse.com/docs/integrations/javascript

# clickhouse-js-node-codingby clickhouse
Reference: https://clickhouse.com/docs/integrations/javascript

`npx skills add https://github.com/clickhouse/clickhouse-js --skill clickhouse-js-node-coding`Download ZIPGitHub

## 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

* 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.

* 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.

* 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.

* 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.

* 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.

* 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.

TaskTriggers / symptomsReference fileConfigure / connect the clientBuilding a `createClient` call, URL parameters, `clickhouse_settings`, default format, custom HTTP headers`reference/client-configuration.md`Ping the serverHealth 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 queriesBinding 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/stringifyPlug 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/`.

* TLS, RBAC / read-only users, deeper SQL-injection guidance — see
`examples/node/security/`.

* `CREATE TABLE` patterns, deployment-shaped connection strings,
replication / sharding choices — see
`examples/node/schema-and-deployments/`.

* Browser, Web Worker, Next.js Edge, Cloudflare Workers — use
`@clickhouse/client-web` and see
`examples/web/`.

## Still Stuck?

* `examples/node/coding/` — the runnable corpus this skill is built on.

* ClickHouse JS client docs

* ClickHouse supported formats

* ClickHouse data types

## More skills from clickhouse
chdb-sqlby clickhouseRun ClickHouse SQL directly in Python — no server needed. Query local files, remote databases, and cloud storage with full ClickHouse SQL power.chdb-datastoreby clickhouseDataStore is a lazy, ClickHouse-backed pandas replacement . Your existing pandas code works unchanged — but operations compile to optimized SQL and execute only when results are needed (e.g., print() , len() , iteration).clickhouse-architecture-advisorby clickhouseMUST USE when designing ClickHouse architectures, selecting between ingestion or modeling patterns, or translating best practices into workload-specific system…clickhouse-best-practicesby clickhouse28 ClickHouse best practices rules organized by schema design, query optimization, and data ingestion strategy. Covers three critical areas: primary key and data type selection (immutable design decisions), JOIN and query optimization, and insert batching with mutation avoidance Includes 28 rules prioritized by impact, with schema design and query optimization rules marked CRITICAL due to ClickHouse's columnar storage and sparse index mechanics Provides structured review procedures for...clickhousectl-cloud-deployby clickhouseUse when a user wants to deploy ClickHouse to the cloud, go to production, use ClickHouse Cloud, host a managed ClickHouse service, or migrate from a local…clickhousectl-local-devby clickhouseUse when a user wants to build an application with ClickHouse, set up a local ClickHouse development environment, install ClickHouse, create a local server,…setupby clickhouseGuides users through setting up the ClickHouse MCP server connection bundled with this plugin. Use when the user first installs the plugin or has trouble…clickhouse-js-node-troubleshootingby clickhouseReference: https://clickhouse.com/docs/integrations/javascript

---

**Source**: https://github.com/clickhouse/clickhouse-js/tree/HEAD/skills/clickhouse-js-node-coding
**Author**: clickhouse
**Discovered via**: mcpservers.org