### Install Web Example Dependencies

Source: https://github.com/clickhouse/clickhouse-js/blob/main/examples/README.md

Navigate to the 'examples/web' directory and install its dependencies before running Web examples.

```bash
# For Web examples
cd examples/web
npm i
```

--------------------------------

### Install Node.js Example Dependencies

Source: https://github.com/clickhouse/clickhouse-js/blob/main/examples/README.md

Navigate to the 'examples/node' directory and install its dependencies before running Node.js examples.

```bash
# For Node.js examples
cd examples/node
npm i
```

--------------------------------

### Install Dependencies and Run Demo

Source: https://github.com/clickhouse/clickhouse-js/blob/main/demo/logs/README.md

Installs project dependencies, seeds the demo database with logs, and starts the development server for the Next.js application.

```bash
npm install
npm run seed
npm run dev
```

--------------------------------

### Install and Setup ClickHouse JS RowBinary Library

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-rowbinary/README.md

Install the library and run the setup command for the skill. This is for using the library as a dependency in your project.

```bash
npm install @clickhouse/rowbinary
npx skills-npm setup
```

--------------------------------

### Run Web Example

Source: https://github.com/clickhouse/clickhouse-js/blob/main/examples/README.md

Execute Web examples using 'tsx' from the 'examples/web' directory.

```bash
# from examples/web
npx tsx --transpile-only coding/array_json_each_row.ts
```

--------------------------------

### Run On-Premise Create Table Example

Source: https://github.com/clickhouse/clickhouse-js/blob/main/examples/README.md

Execute an example for creating a table on an on-premise cluster from the 'examples/node' directory.

```bash
npx tsx --transpile-only schema-and-deployments/create_table_on_premise_cluster.ts
```

--------------------------------

### Run Basic TLS Example

Source: https://github.com/clickhouse/clickhouse-js/blob/main/examples/README.md

Execute a basic TLS example from the 'examples/node' directory after configuring '/etc/hosts'.

```bash
npx tsx --transpile-only security/basic_tls.ts
```

--------------------------------

### Run Node.js Example

Source: https://github.com/clickhouse/clickhouse-js/blob/main/examples/README.md

Execute Node.js examples using 'tsx' from the 'examples/node' directory.

```bash
# from examples/node
npx tsx --transpile-only coding/array_json_each_row.ts
```

```bash
# from examples/node
npx tsx --transpile-only performance/insert_streaming_with_backpressure.ts
```

--------------------------------

### Install @clickhouse/datatype-parser

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/datatype-parser/README.md

Install the library using npm.

```bash
npm install @clickhouse/datatype-parser
```

--------------------------------

### Install @clickhouse/client-web

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/client-web/README.md

Install the package using npm.

```sh
npm i @clickhouse/client-web
```

--------------------------------

### Install Dependencies

Source: https://github.com/clickhouse/clickhouse-js/blob/main/CONTRIBUTING.md

Install all necessary project dependencies using npm.

```bash
npm i
```

--------------------------------

### Run Mutual TLS Example

Source: https://github.com/clickhouse/clickhouse-js/blob/main/examples/README.md

Execute a mutual TLS example from the 'examples/node' directory after configuring '/etc/hosts'.

```bash
npx tsx --transpile-only security/mutual_tls.ts
```

--------------------------------

### Run ClickHouse Cloud Create Table Example

Source: https://github.com/clickhouse/clickhouse-js/blob/main/examples/README.md

Execute a Cloud-specific example for creating a table from the 'examples/node' directory after setting Cloud credentials.

```bash
npx tsx --transpile-only schema-and-deployments/create_table_cloud.ts
```

--------------------------------

### Install @clickhouse/client

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/client-node/README.md

Install the Node.js client for ClickHouse using npm.

```sh
npm i @clickhouse/client
```

--------------------------------

### Install and Build Project

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/datatype-parser/README.md

Install dependencies and build the project. The build process emits JavaScript and TypeScript definition files to the 'dist/' directory.

```bash
npm install
npm run build      # emits dist/ (JS + .d.ts)
npm run typecheck  # tsc --noEmit
```

--------------------------------

### Quick start with @clickhouse/client-web

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/client-web/README.md

Connect to ClickHouse, execute a query, and process the results. Ensure you have a ClickHouse instance running and accessible.

```ts
import { createClient } from "@clickhouse/client-web";

const client = createClient({
  url: "http://localhost:8123",
  username: "default",
  password: "",
});

const resultSet = await client.query({
  query: "SELECT * FROM system.tables",
  format: "JSONEachRow",
});

const tables = await resultSet.json();
console.log(tables);

await client.close();
```

--------------------------------

### Start ClickHouse Instance

Source: https://github.com/clickhouse/clickhouse-js/blob/main/benchmarks/leaks/README.md

Use Docker Compose to start a local ClickHouse instance required for all memory leak tests.

```sh
docker-compose up -d
```

--------------------------------

### Run ClickHouse Docker Container

Source: https://github.com/clickhouse/clickhouse-js/blob/main/demo/logs/README.md

Starts a self-contained ClickHouse instance using Docker Compose. Ensure Node.js 20+ is installed.

```bash
docker compose up -d
```

--------------------------------

### Start Local ClickHouse Instance

Source: https://github.com/clickhouse/clickhouse-js/blob/main/benchmarks/transport/README.md

Use this command to start a local ClickHouse instance using Docker Compose. Ensure you are in the repository root.

```sh
docker-compose up -d
```

--------------------------------

### Repack and Install @clickhouse/rowbinary Library

Source: https://github.com/clickhouse/clickhouse-js/blob/main/demo/logs/README.md

Builds the @clickhouse/rowbinary package, packs it into a tarball, copies it to the demo's vendor directory, and installs it locally. This process is used to pick up changes made in the parent package.

```bash
npm run build && npm pack
cp clickhouse-rowbinary-*.tgz demo/logs/vendor/clickhouse-rowbinary-0.1.0.tgz
cd demo/logs && npm install
```

--------------------------------

### Install and Build ClickHouse JS

Source: https://github.com/clickhouse/clickhouse-js/blob/main/tests/clickhouse-test-runner/README.md

Install dependencies and build the entire project from the repository root. This ensures local checkouts of client packages are used for testing.

```bash
cd /path/to/clickhouse-js
npm install
npm run build
```

--------------------------------

### Quick Start: Connect and Query

Source: https://github.com/clickhouse/clickhouse-js/blob/main/README.md

Connect to ClickHouse and execute a query. Ensure environment variables for connection details are set or provide defaults. The client will be closed automatically after use.

```ts
import { createClient } from "@clickhouse/client"; // or '@clickhouse/client-web'

const client = createClient({
  url: process.env.CLICKHOUSE_URL ?? "http://localhost:8123",
  username: process.env.CLICKHOUSE_USER ?? "default",
  password: process.env.CLICKHOUSE_PASSWORD ?? "",
});

const resultSet = await client.query({
  query: "SELECT * FROM system.tables",
  format: "JSONEachRow",
});

const tables = await resultSet.json();
console.log(tables);

await client.close();
```

--------------------------------

### Clone the Repository

Source: https://github.com/clickhouse/clickhouse-js/blob/main/CONTRIBUTING.md

Fork the repository and clone it to your local machine to start contributing.

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

--------------------------------

### Install AI Agent Skills

Source: https://github.com/clickhouse/clickhouse-js/blob/main/README.md

Install AI agent skills for ClickHouse JS either per project or globally using the CLI.

```sh
# per project
npx skills add ClickHouse/clickhouse-js
# globally
npx skills add ClickHouse/clickhouse-js -g
```

--------------------------------

### Quick Start: Connect and Query ClickHouse

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/client-node/README.md

Connect to a ClickHouse instance, execute a query, and log the results. Ensure environment variables for URL, username, and password are set or use default values.

```ts
import { createClient } from "@clickhouse/client";

const client = createClient({
  url: process.env.CLICKHOUSE_URL ?? "http://localhost:8123",
  username: process.env.CLICKHOUSE_USER ?? "default",
  password: process.env.CLICKHOUSE_PASSWORD ?? "",
});

const resultSet = await client.query({
  query: "SELECT * FROM system.tables",
  format: "JSONEachRow",
});

const tables = await resultSet.json();
console.log(tables);

await client.close();
```

--------------------------------

### Example Git Commit History for a New Client

Source: https://github.com/clickhouse/clickhouse-js/blob/main/ALTERNATIVE_CLIENTS.md

Illustrates a typical commit history when creating a new client by forking an existing one. This history helps reviewers understand the changes relative to the upstream package.

```git
chore: copy client-web to packages/client-bun
feat(client-bun): replace fetch with Bun.fetch primitives
fix(client-bun): adapt streaming to Bun's ReadableStream
test(client-bun): port web integration tests
```

--------------------------------

### Log Messages with User Suggestions and Documentation Links

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/AGENTS.md

When adding log messages that offer suggestions to users, create a unique documentation page and include a link to it within the log message. This example shows how to format such a message.

```typescript
if (some_condition) {
  log_writer.warn({
    message:
      "Example log message with suggestions for users. For more information, see https://github.com/ClickHouse/clickhouse-js/blob/main/docs/socket_hang_up_econnreset.md",
  });
}
```

--------------------------------

### Run Node.js TLS Integration Tests

Source: https://github.com/clickhouse/clickhouse-js/blob/main/CONTRIBUTING.md

Execute integration tests for the Node.js client with TLS enabled, using the 'clickhouse_tls' server container. Ensure containers are started first.

```bash
# Start the containers first:
docker-compose up -d

# and then run the tests (Node.js only):
npm run test:node:integration:tls
```

--------------------------------

### Benchmarking ClickHouse Log Data Decoding

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-rowbinary/case-studies/logs-json-wins.md

Command to run the benchmark tests for ClickHouse data decoding, comparing JSON and RowBinary formats. Ensure Node.js and Vitest are installed.

```bash
npx vitest bench --run tests/logs.bench.ts
```

--------------------------------

### Build and Run Benchmarks

Source: https://github.com/clickhouse/clickhouse-js/blob/main/benchmarks/transport/README.md

Build the workspace packages first, then run the benchmark using tsx. This ensures the @clickhouse/client is resolved correctly at runtime.

```sh
# 1. Build the workspace packages so `@clickhouse/client` resolves at runtime.
npm run build

# 2. Run the benchmark.
npx tsx benchmarks/transport/index.ts
```

--------------------------------

### Interact with the RowBinary Skill

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-rowbinary/README.md

Example of interacting with the RowBinary skill via a conversational interface to generate a reader for specific queries.

```console
> Hey, Claude, tell me what the rowbinary skill can do for me.
> A lot! It generates custom, high-performance RowBinary readers and writers…
> Super, generate a reader for the queries in app/src/model.ts.
< Reading skill clickhouse-js-node-rowbinary…
```

--------------------------------

### Parsed Datatype JSON Structure

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/datatype-parser/reference-cpp-extracted-parser/README.md

The output of the datatype parser is a JSON object representing the parsed datatype. This example shows the structure for a complex Tuple datatype.

```json
{
  "type": "TupleDataType",
  "name": "Tuple",
  "arguments": [
    {
      "type": "DataType",
      "name": "UInt64"
    },
    {
      "type": "DataType",
      "name": "LowCardinality",
      "arguments": [
        {
          "type": "DataType",
          "name": "String"
        }
      ]
    },
    {
      "type": "DataType",
      "name": "Decimal",
      "arguments": [
        {
          "type": "Literal",
          "value_type": "UInt64",
          "value": "18"
        },
        {
          "type": "Literal",
          "value_type": "UInt64",
          "value": "4"
        }
      ]
    },
    {
      "type": "DataType",
      "name": "DateTime64",
      "arguments": [
        {
          "type": "Literal",
          "value_type": "UInt64",
          "value": "9"
        },
        {
          "type": "Literal",
          "value_type": "String",
          "value": "UTC"
        }
      ]
    },
    {
      "type": "DataType",
      "name": "Array",
      "arguments": [
        {
          "type": "DataType",
          "name": "LowCardinality",
          "arguments": [
            {
              "type": "DataType",
              "name": "Nullable",
              "arguments": [
                {
                  "type": "DataType",
                  "name": "String"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "DataType",
      "name": "Map",
      "arguments": [
        {
          "type": "DataType",
          "name": "String"
        },
        {
          "type": "DataType",
          "name": "Array",
          "arguments": [
            {
              "type": "DataType",
              "name": "Nullable",
              "arguments": [
                {
                  "type": "DataType",
                  "name": "Int32"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "EnumDataType",
      "name": "Enum8",
      "values": [
        {
          "name": "active",
          "value": 1
        },
        {
          "name": "closed",
          "value": -2
        }
      ]
    },
    {
      "type": "DataType",
      "name": "Array",
      "arguments": [
        {
          "type": "TupleDataType",
          "name": "Tuple",
          "arguments": [
            {
              "type": "DataType",
              "name": "Float64"
            },
            {
              "type": "DataType",
              "name": "Float64"
            }
          ]
        }
      ]
    },
    {
      "type": "DataType",
      "name": "Nested",
      "arguments": [
        {
          "type": "NameTypePair",
          "name": "k",
          "data_type": {
            "type": "DataType",
            "name": "String"
          }
        },
        {
          "type": "NameTypePair",
          "name": "v",
          "data_type": {
            "type": "DataType",
            "name": "UInt32"
          }
        }
      ]
    },
    {
      "type": "DataType",
      "name": "FixedString",
      "arguments": [
        {
          "type": "Literal",
          "value_type": "UInt64",
          "value": "16"
        }
      ]
    },
    {
      "type": "DataType",
      "name": "Dynamic",
      "arguments": [
        {
          "type": "Function",
          "name": "equals",
          "is_operator": true,
          "arguments": [
            {
              "type": "Identifier",
              "name": "max_types"
            },
            {
              "type": "Literal",
              "value_type": "UInt64",
              "value": "8"
            }
          ]
        }
      ]
    },
    {
      "type": "DataType",
      "name": "Variant",
      "arguments": [
        {
          "type": "DataType",
          "name": "UInt64"
        },
        {
          "type": "DataType",
          "name": "String"
        },
        {
          "type": "DataType",
          "name": "Array",
          "arguments": [
            {
              "type": "DataType",
              "name": "UInt8"
            }
          ]
        }
      ]
    },
    {
      "type": "DataType",
      "name": "Object",
      "arguments": [
        {
          "type": "Literal",
          "value_type": "String",
          "value": "json"
        }
      ]
    }
  ],
  "element_names": [
    "id",
    "name",
    "price",
    "ts",
    "tags",
    "attrs",
    "status",
    "coords",
    "meta",
    "fixed",
    "dyn",
    "variant",
    "raw"
  ]
}
```

--------------------------------

### Run Benchmarks with Custom Configuration

Source: https://github.com/clickhouse/clickhouse-js/blob/main/benchmarks/transport/README.md

Execute the benchmark with custom environment variables to adjust parameters like request count and download rows. The build command is chained before running the benchmark.

```sh
npm run build \
&& LATENCY_REQUESTS=500 DOWNLOAD_ROWS=5000000 ITERATIONS=20 \
npx tsx benchmarks/transport/index.ts
```

--------------------------------

### Configure and Build ClickHouse Parser

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/datatype-parser/reference-cpp-extracted-parser/README.md

Configure the build with CMake, specifying the ClickHouse binary path, then build the project. This prepares the parser for testing.

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCLICKHOUSE_BINARY=/work/ClickHouse/build/programs/clickhouse
cmake --build build
```

--------------------------------

### Set ClickHouse Cloud Environment Variables

Source: https://github.com/clickhouse/clickhouse-js/blob/main/examples/README.md

Configure these environment variables for Node.js client to connect to ClickHouse Cloud. For Web client, set them within the example code.

```bash
export CLICKHOUSE_CLOUD_URL=https://<your-clickhouse-cloud-hostname>:8443
export CLICKHOUSE_CLOUD_PASSWORD=<your-clickhouse-cloud-password>
```

--------------------------------

### Create Table and Insert QBit Data

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-coding/reference/data-types.md

Demonstrates creating a table with a QBit column and inserting vector data using JSONEachRow format. Ensure the `allow_experimental_qbit_type` setting is enabled for ClickHouse versions 25.10.

```typescript
import { createClient } from "@clickhouse/client";

const tableName = `chjs_qbit`;
const client = createClient({
  clickhouse_settings: {
    // QBit introduced in ClickHouse 25.10 (experimental), GA since 26.x.
    // This setting is required only on 25.10; harmless/no-op on >= 26.x.
    allow_experimental_qbit_type: 1,
  },
});

await client.command({
  query: `
    CREATE OR REPLACE TABLE ${tableName}
    (
      id  UInt64,
      vec QBit(Float32, 8)
    )
    ENGINE MergeTree
    ORDER BY id
  `,
});

// Even though QBit is stored internally as a Tuple of FixedString bit planes,
// JSON* formats accept (and return) the original Array(Float32) shape.
const values = [
  { id: 1, vec: [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0] },
  { id: 2, vec: [8.0, 7.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0] },
  { id: 3, vec: [1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5] },
];
await client.insert({
  table: tableName,
  format: "JSONEachRow",
  values,
});

// Round-trip via JSONEachRow: the vec column comes back as an array of numbers.
const rs = await client.query({
  query: `SELECT id, vec FROM ${tableName} ORDER BY id`,
  format: "JSONEachRow",
});
const rows = await rs.json<{ id: number; vec: number[] }>();
// vec comes back unchanged as the original Float32 array.
console.log(rows);

// Approximate vector search via L2DistanceTransposed.
// The third argument is the precision in bits: lower = less I/O, less accurate.
const search = await client.query({
  query: `
    SELECT id,
           L2DistanceTransposed(vec, {ref:Array(Float32)}, {bits:UInt8}) AS dist
    FROM ${tableName}
    ORDER BY dist ASC
  `,
  query_params: {
    ref: [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0],
    bits: 16,
  },
  format: "JSONEachRow",
});
const nearest = await search.json<{ id: number; dist: number }>();
// The reference vector is exactly row #1, so it's the closest match (dist 0).
console.log(nearest);

await client.close();
```

--------------------------------

### Start Long-Running Command with AbortController

Source: https://github.com/clickhouse/clickhouse-js/blob/main/docs/howto/long_running_queries.md

Initiate a long-running command without awaiting its completion immediately. Attach an `AbortController` to allow for dropping the HTTP connection while the server-side query continues.

```typescript
const abortController = new AbortController();

const commandPromise = client
  .command({
    query: `INSERT INTO my_table SELECT * FROM source_table`,
    query_id: queryId,
    abort_signal: abortController.signal,
  })
  .catch((err) => {
    if (err instanceof Error && err.message.includes("abort")) {
      // Expected — we aborted the request intentionally.
    } else {
      throw err;
    }
  });
```

--------------------------------

### Minimal Client Configuration

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-coding/reference/client-configuration.md

Set up a basic ClickHouse client using explicit fields for URL, username, password, and database. Defaults are provided if environment variables are not set. Remember to close the client when your application shuts down.

```typescript
import { createClient } from "@clickhouse/client";

const client = createClient({
  url: process.env.CLICKHOUSE_URL, // defaults to 'http://localhost:8123'
  username: process.env.CLICKHOUSE_USER, // defaults to 'default'
  password: process.env.CLICKHOUSE_PASSWORD, // defaults to ''
  database: "analytics", // defaults to 'default'
});
// ... your queries ...
await client.close();
```

--------------------------------

### Enable Testing and Add Test Subdirectory

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/datatype-parser/reference-cpp-extracted-parser/CMakeLists.txt

Enables the testing framework and includes the 'test' subdirectory for test cases.

```cmake
enable_testing()
add_subdirectory(test)
```

--------------------------------

### Run Web Local Single Node Integration Tests

Source: https://github.com/clickhouse/clickhouse-js/blob/main/CONTRIBUTING.md

Execute integration tests for the Web client against a local single-node ClickHouse server.

```bash
# Run the tests (Web):
npm run test:web
```

--------------------------------

### Optimized RowBinary Reader Generated by Skill

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-rowbinary/README.md

An example of a highly optimized reader generated by the skill. It uses direct memory access and a single bounds check for improved performance, suitable for fixed-width rows.

```typescript
const readOrderRowFast: Reader<OrderRow> = (s) => {
  const { buf, view } = s;
  const o = advance(s, 26); // one bounds check for the whole 26-byte row
  const id = buf[o]!;
  const uid = formatUUIDTable(buf.subarray(o + 1, o + 17));
  const price: DecimalValue = [view.getBigInt64(o + 17, true), 2];
  const status = view.getInt8(o + 25);
  return { id, uid, price, status };
};
```

--------------------------------

### Run Web Unit Tests

Source: https://github.com/clickhouse/clickhouse-js/blob/main/CONTRIBUTING.md

Execute unit tests for the Web client package. This command also runs the common unit tests.

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

--------------------------------

### Eager Log Level Checks in TypeScript

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/AGENTS.md

When adding log messages, use eager log level checks to prevent unnecessary calculations for logs that won't be emitted. This example demonstrates a WARN level check.

```typescript
if (log_level <= ClickHouseLogLevel.WARN) {
  log_writer.warn({
    message: "Example log message",
  });
}
```

--------------------------------

### Live Oracle Comparison Test

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/datatype-parser/README.md

Perform a live comparison against a running ClickHouse server, bypassing snapshots. Useful for iterative development.

```bash
npm run test:oracle -- --clickhouse /path/to/clickhouse
```

--------------------------------

### Run Web Cloud Integration Tests

Source: https://github.com/clickhouse/clickhouse-js/blob/main/CONTRIBUTING.md

Execute integration tests for the Web client against a ClickHouse Cloud instance. Ensure cloud connection environment variables are set.

```bash
# Web:
npm run test:web:integration:cloud
```

--------------------------------

### Suppress Nested HTTP Spans

Source: https://github.com/clickhouse/clickhouse-js/blob/main/docs/howto/tracing.md

This recipe suppresses duplicate child HTTP spans generated by `@opentelemetry/instrumentation-http` for ClickHouse operations. It utilizes `suppressTracing` from `@opentelemetry/core` to run operations within a suppressed context. Ensure you have the necessary OpenTelemetry packages installed.

```typescript
import { context, trace } from "@opentelemetry/api";
import { suppressTracing } from "@opentelemetry/core";
import { createClient, type ClickHouseTracer } from "@clickhouse/client";

const otelTracer = trace.getTracer("@clickhouse/client");
const tracer: ClickHouseTracer = {
  startActiveSpan: (name, options, fn) =>
    otelTracer.startActiveSpan(name, options, (span) =>
      context.with(suppressTracing(context.active()), () => fn(span)),
    ),
};

const client = createClient({ tracer });

```

--------------------------------

### Decode RowBinary Data with ClickHouse JS Client

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-rowbinary/README.md

This example demonstrates how to use the @clickhouse/rowbinary library with the ClickHouse JS client to fetch and decode RowBinary formatted data. Ensure you use `client.exec` with `FORMAT RowBinary` in your query and pass the raw byte stream to `streamRowBatches`.

```typescript
import {
  type Reader,
  readUInt8,
  readInt8,
  readUUID,
  formatUUID,
  readDecimal64,
  type DecimalValue,
  streamRowBatches,
} from "@clickhouse/rowbinary";
import { createClient } from "@clickhouse/client";

type OrderRow = {
  id: number;
  uid: string;
  price: DecimalValue;
  status: number;
};

const readOrderRow: Reader<OrderRow> = (s) => ({
  id: readUInt8(s),
  uid: formatUUID(readUUID(s)),
  price: readDecimal64(2)(s),
  status: readInt8(s), // raw enum int; `readEnum8(map)` resolves it to the name
});

// `exec` resolves to a Node `Stream.Readable`. It is already an
// `AsyncIterable<Uint8Array>` (chunks are `Buffer`/`Uint8Array`, which
// `streamRowBatches` normalizes), so pass `stream` straight in:

const client = createClient();

const { stream } = await client.exec({
  query: "SELECT id, uid, price, status FROM orders FORMAT RowBinary",
});

for await (const rows of streamRowBatches(stream, readOrderRow)) {
  for (const row of rows) console.log(row); // { id, uid, price: [unscaled, scale], status }
}

await client.close();

```

--------------------------------

### Per-Client vs Per-Request `clickhouse_settings`

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-coding/reference/client-configuration.md

Demonstrates how to apply `clickhouse_settings` globally to a client instance and how to override them for specific query calls. Client-level settings serve as defaults for all requests.

```typescript
const client = createClient({
  clickhouse_settings: {
    output_format_json_quote_64bit_integers: 0, // applied to every request
  },
});

const rows = await client.query({
  query: "SELECT number FROM system.numbers LIMIT 2 FORMAT JSONEachRow",
  clickhouse_settings: {
    output_format_json_quote_64bit_integers: 1, // overrides client default for this call
  },
});
```

--------------------------------

### Build and Test ClickHouse Data-Type Parser

Source: https://github.com/clickhouse/clickhouse-js/blob/main/packages/datatype-parser/reference-cpp-extracted-parser/README.md

Commands to clean the build directory, configure the project with CMake for a Release build, and build the project.

```bash
rm -rf build # clean the build dir for a fresh run
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

--------------------------------

### Inserting Decimal Values

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-coding/reference/insert-values.md

When inserting Decimal values, ensure they are passed as strings in JSON formats to prevent precision loss in JavaScript. Floats should not be used for decimal values; use a proper decimal library and serialization strategy to string. The example includes creating a table with various Decimal types and then inserting string representations of these values.

```typescript
await client.command({
  query: `
    CREATE OR REPLACE TABLE prices (
      id     UInt32,
      dec32  Decimal(9, 2),
      dec64  Decimal(18, 3),
      dec128 Decimal(38, 10),
      dec256 Decimal(76, 20)
    )
    ENGINE MergeTree ORDER BY id
  `,
});

await client.insert({
  table: "prices",
  format: "JSONEachRow",
  values: [
    {
      id: 1,
      dec32: "1234567.89",
      dec64: "123456789123456.789",
      dec128: "1234567891234567891234567891.1234567891",
      dec256:
        "12345678912345678912345678911234567891234567891.12345678911234567891",
    },
  ],
});
```

--------------------------------

### Ping with Query Execution Check

Source: https://github.com/clickhouse/clickhouse-js/blob/main/skills/clickhouse-js-node-coding/reference/ping.md

Demonstrates using ping({ select: true }) to verify not only network connectivity but also that the server can process queries and that authentication is successful. This is useful for readiness probes.

```typescript
const r = await client.ping({ select: true });
// success only if the server is reachable AND auth is correct AND it can run queries
```

--------------------------------

### Run Node.js Local Single Node Integration Tests

Source: https://github.com/clickhouse/clickhouse-js/blob/main/CONTRIBUTING.md

Execute integration tests for the Node.js client against a local single-node ClickHouse server.

```bash
# Run tests (Node.js):
npm run test:node:integration
```

--------------------------------

### Configure PATH for ClickHouse Test Runner

Source: https://github.com/clickhouse/clickhouse-js/blob/main/tests/clickhouse-test-runner/README.md

Prepend the test runner's bin directory to your PATH for the current shell session. This allows the official runner to use the local shim executables.

```bash
export PATH="/path/to/clickhouse-js/tests/clickhouse-test-runner/bin:$PATH"
```