Examples are split first by client flavor, then by use case:
examples/
├── node/ # @clickhouse/client (Node.js)
│ ├── coding/
│ ├── performance/
│ ├── troubleshooting/
│ ├── security/
│ ├── schema-and-deployments/
│ └── resources/ # shared fixture data
└── web/ # @clickhouse/client-web
├── coding/
├── performance/
├── troubleshooting/
├── security/
└── schema-and-deployments/
The use-case folders are intent-driven ("what is the agent or user trying to do?")
so each folder is a tight, self-contained corpus that can back a focused AI agent
skill. A few examples appear in more than one folder on purpose — duplication
keeps each skill self-contained instead of forcing cross-folder references. When
running examples, every duplicated file has one primary location and the
secondary copies are excluded from the Vitest runner (see
examples/node/vitest.config.ts and
examples/web/vitest.config.ts). When you edit a
duplicated example, update all copies.
examples/web only has a small performance/ folder — most performance
examples depend on Node-only APIs (Node streams, node:fs, Parquet file I/O)
and live exclusively under examples/node/performance/.
Most general-purpose examples (configuration, ping, inserts, selects, parameters,
sessions, etc.) exist in both node/ and web/. The only differences are the
import statement and a few platform-specific adjustments (e.g.
globalThis.crypto.randomUUID() for the Web client vs Node's crypto module).
If something is missing, or you found a mistake in one of these examples, please open an issue or a pull request, or contact us.
"How do I do X with the client?" — connect, configure, ping, basic insert/select, parameter binding, sessions, data types, and custom JSON handling.
"How do I make ingestion or queries fast and scalable?" — async inserts without
waiting, streaming inserts and selects with backpressure, file-stream ingestion,
progress streaming, and server-side bulk moves. Most performance examples are
Node-only because they depend on Node streams, node:fs, or Parquet file I/O;
a small subset that uses only Web-platform APIs is also available under
examples/web/performance/.
"Something is failing, slow, or hanging — how do I diagnose or recover?" — cancellation, timeouts, progress headers, server-side error surfaces, and number precision pitfalls.
"How do I run securely?" — TLS (basic and mutual), role-based access, read-only users, and SQL-injection-safe parameter binding.
| Example | Node | Web |
|---|---|---|
| Basic TLS authentication (Node.js only) | node/security/basic_tls.ts | — |
| Mutual TLS authentication (Node.js only) | node/security/mutual_tls.ts | — |
| Read-only user limitations | node/security/read_only_user.ts | web/security/read_only_user.ts |
| Using one or more roles | node/security/role.ts | web/security/role.ts |
| Query parameter binding | node/security/query_with_parameter_binding.ts | web/security/query_with_parameter_binding.ts |
| Query parameter binding with special chars | node/security/query_with_parameter_binding_special_chars.ts | web/security/query_with_parameter_binding_special_chars.ts |
"How do I create tables and target different deployments?" — single-node, on-premise cluster, ClickHouse Cloud, column-shape features, and deployment-shaped connection strings.
| Example | Node | Web |
|---|---|---|
| Single-node deployment | node/schema-and-deployments/create_table_single_node.ts | web/schema-and-deployments/create_table_single_node.ts |
| On-premise cluster | node/schema-and-deployments/create_table_on_premise_cluster.ts | web/schema-and-deployments/create_table_on_premise_cluster.ts |
| ClickHouse Cloud | node/schema-and-deployments/create_table_cloud.ts | web/schema-and-deployments/create_table_cloud.ts |
| Insert into a table with ephemeral columns | node/schema-and-deployments/insert_ephemeral_columns.ts | web/schema-and-deployments/insert_ephemeral_columns.ts |
| Insert excluding columns | node/schema-and-deployments/insert_exclude_columns.ts | web/schema-and-deployments/insert_exclude_columns.ts |
| Client configuration via URL parameters | node/schema-and-deployments/url_configuration.ts | web/schema-and-deployments/url_configuration.ts |
Environment requirements for most examples:
- Node.js 20+
- NPM
- Docker Compose
The event-loop delay example only needs Node.js and NPM. It does not connect to ClickHouse.
Run ClickHouse in Docker from the root folder of this repository:
docker-compose up -dThis will create two local ClickHouse instances: one with plain authentication and one that requires TLS.
Each subdirectory (node and web) is a fully independent npm package with its
own package.json, tsconfig.json, eslint.config.mjs, and Vitest runner
config — they do not share any configuration with the repository root. Install
dependencies in the subdirectory matching the example you want to run:
# For Node.js examples
cd examples/node
npm i
# For Web examples
cd examples/web
npm iThen, you should be able to run any sample program by pointing tsx at its
category-relative path, for example:
# from examples/node
npx tsx coding/array_json_each_row.ts
npx tsx performance/insert_streaming_with_backpressure.ts
# from examples/web
npx tsx coding/array_json_each_row.tsYou will need to add server.clickhouseconnect.test to your /etc/hosts to
make it work, as self-signed certificates are used in these examples.
Execute the following command to add the required /etc/hosts entry:
sudo -- sh -c "echo 127.0.0.1 server.clickhouseconnect.test >> /etc/hosts"After that, you should be able to run the examples (from examples/node):
npx tsx security/basic_tls.ts
npx tsx security/mutual_tls.ts
npx tsx schema-and-deployments/create_table_on_premise_cluster.ts- for
*_cloud.tsexamples, Docker containers are not required, but you need to set some environment variables first for the Node.js client:
export CLICKHOUSE_CLOUD_URL=https://<your-clickhouse-cloud-hostname>:8443
export CLICKHOUSE_CLOUD_PASSWORD=<your-clickhouse-cloud-password>and for the Web client, you need to set these variables in the examples themselves.
You can obtain these credentials in the ClickHouse Cloud console (check the docs for more information).
Cloud examples assume that you are using the default user and database.
Run one of the Cloud examples (from examples/node):
npx tsx schema-and-deployments/create_table_cloud.ts
The following environment variables control behavior when running examples in automated environments (e.g., CI):
-
CLICKHOUSE_CLUSTER_URL— Overrides the URL for on-premise cluster examples. Default:http://localhost:8127. -
CLICKHOUSE_CLOUD_URL/CLICKHOUSE_CLOUD_PASSWORD— When both are set, the Cloud examples (*_cloud.ts) connect to the specified ClickHouse Cloud instance. When unset, these examples do not skip automatically and will fail because the required Cloud configuration is missing.
A handful of examples live in more than one category folder so each category remains a self-contained skill corpus. The current duplicates are:
| Logical example | Primary location | Secondary copies |
|---|---|---|
async_insert.ts |
coding/ |
performance/ (Node only) |
insert_from_select.ts |
coding/ |
performance/ (Node only) |
ping_non_existing_host.ts |
coding/ |
troubleshooting/ |
custom_json_handling.ts |
coding/ |
troubleshooting/ |
query_with_parameter_binding.ts |
coding/ |
security/ |
query_with_parameter_binding_special_chars.ts |
coding/ |
security/ |
insert_ephemeral_columns.ts |
coding/ |
schema-and-deployments/ |
insert_exclude_columns.ts |
coding/ |
schema-and-deployments/ |
url_configuration.ts |
coding/ |
schema-and-deployments/ |
read_only_user.ts |
security/ |
troubleshooting/ |
When you change a duplicated example, update every copy in both node/ and
web/ (where applicable). Only the primary copy is executed by the Vitest
runner; the secondary copies are excluded in
examples/node/vitest.config.ts and
examples/web/vitest.config.ts.