Updates

.github/instructions/review.instructions.md

@@ -0,0 +1,18 @@
+---
+applyTo: "**"
+excludeAgent: "cloud-agent"
+---
+
+## UX
+
+Skip the PR overview comment if possible.
+
+## Handling change
+
+When you're adding comments that require human attention because they need maintainer triage, a policy or product decision, or clarification before the PR author can act, add a "take-a-look" label to the PR.
+
+In other cases when you've found a meaningful change to make, make it and push changes when the PR context allows writes.
+
+## Review focus
+
+When reviewing PRs to the `release` branch focus on flagging breaking changes and security issues in the broader context, as PRs to the `release` branch are normally bigger and include a cumulative change from a number of PRs.

.github/workflows/examples.yml

@@ -0,0 +1,120 @@
+name: 'examples'
+
+permissions: {}
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - release
+    paths-ignore:
+      - '**/*.md'
+      - 'LICENSE'
+      - 'benchmarks/**'
+  pull_request:
+    paths-ignore:
+      - '**/*.md'
+      - 'LICENSE'
+      - 'benchmarks/**'
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.ref }}'
+  cancel-in-progress: true
+
+env:
+  OTEL_SERVICE_NAME: vitest
+  OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
+  OTEL_EXPORTER_OTLP_HEADERS: 'authorization=${{ secrets.OTEL_EXPORTER_OTLP_API_KEY }}'
+  OTEL_RESOURCE_ATTRIBUTES: 'service.namespace=clickhouse-js,deployment.environment=ci'
+  VITEST_OTEL_ENABLED: 'true'
+  VITEST_COVERAGE: 'true'
+
+jobs:
+  code-quality:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        package: [node, web]
+    defaults:
+      run:
+        working-directory: examples/${{ matrix.package }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup NodeJS
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: |
+          npm install
+
+      - name: Typecheck
+        run: |
+          npm run typecheck
+
+      - name: Run linting
+        run: |
+          npm run lint
+
+  run-examples:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        clickhouse: [head, latest]
+        package: [node, web]
+    defaults:
+      run:
+        working-directory: examples/${{ matrix.package }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Start ClickHouse (version - ${{ matrix.clickhouse }}) in Docker
+        uses: isbang/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.2
+        env:
+          CLICKHOUSE_VERSION: ${{ matrix.clickhouse }}
+        with:
+          compose-file: 'docker-compose.yml'
+          down-flags: '--volumes'
+
+      - name: Setup NodeJS
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+
+      - name: Install examples dependencies
+        run: |
+          npm install
+
+      - name: Install Playwright Chromium
+        if: matrix.package == 'web'
+        run: |
+          npx playwright install chromium
+
+      - name: Add ClickHouse TLS instance to /etc/hosts
+        run: |
+          echo "127.0.0.1 server.clickhouseconnect.test" | sudo tee -a /etc/hosts
+
+      - name: Warm up system.query_log
+        run: |
+          docker exec clickhouse-js-clickhouse-server clickhouse-client --query "SELECT 1"
+          sleep 8
+
+      - name: Run examples
+        env:
+          CLICKHOUSE_CLOUD_URL: https://${{ secrets.INTEGRATIONS_TEAM_TESTS_CLOUD_HOST_SMT_PROD }}/
+          CLICKHOUSE_CLOUD_PASSWORD: ${{ secrets.INTEGRATIONS_TEAM_TESTS_CLOUD_PASSWORD_SMT_PROD }}
+        run: |
+          npm run run-examples
+
+  success:
+    needs: ['code-quality', 'run-examples']
+    runs-on: ubuntu-latest
+    steps:
+      - name: All examples checks passed
+        run: echo "All examples checks passed! 🎉"

.github/workflows/github-export-otel.yml

@@ -6,6 +6,7 @@ on:
     # that should trigger workflow telemetry exporting explicitly.
     workflows:
       - tests
+      - examples
     types: [completed]
 
 permissions:

.github/workflows/tests.yml

@@ -59,88 +59,6 @@ jobs:
         run: |
           npm run lint
 
-  code-quality-examples:
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        package: [node, web]
-    defaults:
-      run:
-        working-directory: examples/${{ matrix.package }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Setup NodeJS
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
-        with:
-          node-version: 24
-
-      - name: Install dependencies
-        run: |
-          npm install
-
-      - name: Typecheck
-        run: |
-          npm run typecheck
-
-      - name: Run linting
-        run: |
-          npm run lint
-
-  run-examples:
-    timeout-minutes: 10
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        clickhouse: [head, latest]
-        package: [node, web]
-    defaults:
-      run:
-        working-directory: examples/${{ matrix.package }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Start ClickHouse (version - ${{ matrix.clickhouse }}) in Docker
-        uses: isbang/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.2
-        env:
-          CLICKHOUSE_VERSION: ${{ matrix.clickhouse }}
-        with:
-          compose-file: 'docker-compose.yml'
-          down-flags: '--volumes'
-
-      - name: Setup NodeJS
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
-        with:
-          node-version: 24
-
-      - name: Install examples dependencies
-        run: |
-          npm install
-
-      - name: Install Playwright Chromium
-        if: matrix.package == 'web'
-        run: |
-          npx playwright install chromium
-
-      - name: Add ClickHouse TLS instance to /etc/hosts
-        run: |
-          echo "127.0.0.1 server.clickhouseconnect.test" | sudo tee -a /etc/hosts
-
-      - name: Warm up system.query_log
-        run: |
-          docker exec clickhouse-js-clickhouse-server clickhouse-client --query "SELECT 1"
-          sleep 8
-
-      - name: Run examples
-        env:
-          CLICKHOUSE_CLOUD_URL: https://${{ secrets.INTEGRATIONS_TEAM_TESTS_CLOUD_HOST_SMT_PROD }}/
-          CLICKHOUSE_CLOUD_PASSWORD: ${{ secrets.INTEGRATIONS_TEAM_TESTS_CLOUD_PASSWORD_SMT_PROD }}
-        run: |
-          npm run run-examples
-
   common-unit-tests-node:
     timeout-minutes: 5
     runs-on: ubuntu-latest
@@ -576,8 +494,6 @@ jobs:
     needs:
       [
         'code-quality',
-        'code-quality-examples',
-        'run-examples',
         'common-unit-tests-node',
         'common-unit-tests-web',
         'node-unit-tests',

.github/workflows/upstream-sql-tests.yml

@@ -86,7 +86,6 @@ jobs:
           down-flags: '--volumes'
 
       - name: Build test runner
-        working-directory: tests/clickhouse-test-runner
         run: |
           npm install
           npm run build

AGENTS.md

@@ -82,6 +82,7 @@ The [`tests/clickhouse-test-runner`](tests/clickhouse-test-runner) harness is a
 ### What the harness does
 
 - Wraps `@clickhouse/client` in a tiny CLI (`bin/clickhouse` → `dist/main.js`) that mimics enough of the upstream `clickhouse-client` binary (same flags, `extract-from-config` shortcut, stdin/`--query` behavior) for the Python `tests/clickhouse-test` runner to drive it without modification.
+- The runner is an npm workspace of the root `clickhouse-js` package, so `npm install` from the repo root links `@clickhouse/client` and `@clickhouse/client-common` from the local checkout instead of resolving them from the npm registry. Always install + build from the repo root (`npm install && npm run build`) so the harness exercises the code under review rather than the last published client.
 - The CI matrix runs the harness against ClickHouse `latest` and `head` so that we exercise `@clickhouse/client` against both server versions and detect server regressions. The allowlist is also split into round-robin shards (`SHARD_INDEX` / `SHARD_TOTAL`) so each matrix job stays at roughly one minute; bump both the `shard` matrix values and the `SHARD_TOTAL` env value in the workflow together if per-shard runtime climbs back above ~1 minute.
 - Reads the curated test list from [`upstream-allowlist.txt`](tests/clickhouse-test-runner/upstream-allowlist.txt) (one test name per line, `#` for comments) and forwards them as positional arguments to `tests/clickhouse-test`.
 - The `SERVER_SETTINGS`/`CLIENT_ONLY_SETTINGS` allowlists in [`src/settings.ts`](tests/clickhouse-test-runner/src/settings.ts) are copied from the Java port and may need periodic resync as ClickHouse adds or reclassifies settings.