Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
220 lines (145 loc) · 6.6 KB

CONTRIBUTING.md

File metadata and controls

220 lines (145 loc) · 6.6 KB
Raw

Getting started

ClickHouse js client is an open-source project, and we welcome any contributions from the community. Please share your ideas, contribute to the codebase, and help us maintain up-to-date documentation.

Set up environment

You have installed:

  • a compatible version of Node.js: v20.x, v22.x, v24.x or v26.x
  • NPM >= 9.x

Create a fork of the repository and clone it

git clone https://github.com/[YOUR_USERNAME]/clickhouse-js
cd clickhouse-js

Install dependencies

npm i

Add /etc/hosts entry

Required for TLS tests. The generated certificates assume TLS requests use server.clickhouseconnect.test as the hostname. See tls.test.ts for more details.

sudo -- sh -c "echo 127.0.0.1 server.clickhouseconnect.test >> /etc/hosts"

Style Guide

We use automatic code formatting with prettier and linting with eslint, both should be installed after running npm i.

Additionally, every commit should trigger a Husky Git hook that applies prettier to the staged files via lint-staged automatically. eslint is not run by the commit hook; it runs in CI (with --max-warnings=0), so run it manually with npm run lint (or npm run lint:fix) before pushing.

Testing

Whenever you add a new feature to the package or fix a bug, we strongly encourage you to add appropriate tests to ensure everyone in the community can safely benefit from your contribution.

Tooling

We use Vitest as the test runner and the testing framework. It covers a variety of testing needs, including unit and integration tests, and supports Node.js, Web environments, and edge runtimes.

The repository keeps two Vitest configuration files, embedded in the client packages:

  • packages/client-node/vitest.config.ts - Tests for the Node.js client package
  • packages/client-web/vitest.config.ts - Tests for the Web client package

The shared (common) sources live in packages/client-common and are bundled into both clients; the common specs are run as part of the Node.js and Web test suites, so the common code is covered without a separate config. Each config supports multiple test modes controlled by the TEST_MODE environment variable, allowing different test scenarios (unit, integration, TLS, etc.) to be run with a single configuration file.

Type checking and linting

Both checks can be run manually:

npm run typecheck
npm run lint:fix

Formatting can be checked or applied repo-wide with:

npm run prettier:check
npm run prettify

The Husky Git hook formats staged files with prettier on commit, but does not run eslint; make sure to run npm run lint before pushing, as CI enforces it with zero warnings.

Every ESLint rule is configured as a warn (the only hard errors come from the TypeScript compiler, i.e. npm run typecheck). Because CI runs eslint --max-warnings=0, any ESLint warning still fails the build, so treat all warnings as errors that must be fixed before merging.

Running unit tests

Does not require a running ClickHouse server.

# Run Node.js unit tests (also runs the common unit tests)
npm run test:node:unit

# Run Web unit tests (also runs the common unit tests)
npm run test:web:unit

Running integration tests

Integration tests use a running ClickHouse server in Docker or the Cloud.

CLICKHOUSE_TEST_ENVIRONMENT environment variable is used to switch between testing modes.

There are three possible options:

  • local_single_node (default)
  • local_cluster
  • cloud

The main difference will be in table definitions, as having different engines in different setups is required. Any insert*.test.ts can be a good example of that. Additionally, there is a slightly different test client creation when using Cloud, as we need credentials.

Local single node integration tests

Used when CLICKHOUSE_TEST_ENVIRONMENT is omitted or set to local_single_node.

Start a single ClickHouse server using Docker compose:

docker-compose up -d

Run the tests (Node.js):

npm run test:node:integration

Run the tests (Web):

npm run test:web

Running TLS integration tests

Basic and mutual TLS certificates tests, using clickhouse_tls server container.

Start the containers first:

docker-compose up -d

and then run the tests (Node.js only):

npm run test:node:integration:tls

Local two nodes cluster integration tests

Used when CLICKHOUSE_TEST_ENVIRONMENT is set to local_cluster.

Run the tests (Node.js):

npm run test:node:integration:local_cluster

Run the tests (Web):

npm run test:web:integration:local_cluster

Cloud integration tests

Used when CLICKHOUSE_TEST_ENVIRONMENT is set to cloud.

Two environment variables will be required to connect to the cluster in the Cloud. You can obtain it after creating an instance in the Control Plane.

CLICKHOUSE_CLOUD_HOST=<host>
CLICKHOUSE_CLOUD_PASSWORD=<password>;

With these environment variables set, you can run the tests.

Node.js:

npm run test:node:integration:cloud

Web:

npm run test:web:integration:cloud

CI

GitHub Actions should execute integration test jobs for both Node.js and Web versions in parallel after we complete the TypeScript type check, lint check, and Node.js unit tests.

Typecheck + Lint + Node.js client unit tests
├─ Node.js client integration + TLS tests (single local node in Docker)
├─ Node.js client integration tests (a cluster of local two nodes in Docker)
├─ Node.js client integration tests (Cloud)
├─ Web client integration tests (single local node in Docker)
├─ Web client integration tests (a cluster of local two nodes in Docker)
└─ Web client integration tests (Cloud)

Test Coverage

The average reported test coverage is above 90%. We generally aim towards this threshold, if it deems reasonable.

Currently, automatic coverage reports are disabled. See #177, as it should be restored in the scope of that issue.

Running upstream ClickHouse SQL tests

The tests/clickhouse-test-runner directory contains a Node.js port of clickhouse-client that lets tests/clickhouse-test from ClickHouse/ClickHouse exercise the JS client against the upstream SQL test suite. This harness helps validate that @clickhouse/client behaves correctly against real ClickHouse tests. See the clickhouse-test-runner README for setup and usage instructions.