Release 1.18.5

.claude/skills/setup/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: setup
+description: >
+  Set up the `clickhouse-js` repository in a fresh checkout so the agent can run
+  tests, lints, type checks, builds, or examples. Use this skill before invoking
+  any `npm run test:*`, `npm run lint`, `npm run typecheck`, `npm run build`, or
+  `npm run run-examples` script — or after pulling changes that touch any
+  `package.json` (root, `examples/node`, or `examples/web`). Covers Node.js
+  version requirements, installing dependencies across the npm workspaces and
+  the two independent example packages, building the workspace packages so
+  inter-package imports resolve, and starting ClickHouse via Docker Compose for
+  integration tests. Do NOT use this skill for downstream user projects that
+  merely depend on `@clickhouse/client` or `@clickhouse/client-web`; it is
+  specific to contributing to the `ClickHouse/clickhouse-js` repo itself.
+---
+
+# clickhouse-js Repository Setup
+
+Use this skill before running any of the `npm run test:*`, `npm run lint`, `npm run typecheck`, or `npm run build` scripts in a fresh checkout (or after pulling changes that touch `package.json` files).
+
+## Prerequisites
+
+- **Node.js 22 recommended** (matches `.nvmrc`). The root `package.json` declares `"engines": { "node": ">=20.19.0" }`, and CI tests Node 20, 22, and 24.
+- **Docker** with the Compose plugin (`docker compose ...`). Required only for integration tests and any example that talks to a real server.
+
+## 1. Install dependencies
+
+This is an npm workspaces repo (`packages/*`), with two additional independent example packages (`examples/node`, `examples/web`) that have their own `package.json` and are **not** part of the workspaces.
+
+Install all three:
+
+```bash
+npm install
+npm --prefix examples/node install
+npm --prefix examples/web install
+```
+
+The root `postinstall` script patches `node_modules/parquet-wasm/package.json`; it runs automatically as part of `npm install`.
+
+## 2. Build the workspace packages
+
+The workspace packages (`@clickhouse/client-common`, `@clickhouse/client`, `@clickhouse/client-web`) must be built before some tests, examples, and typechecks can resolve their inter-package imports:
+
+```bash
+npm run build
+```
+
+This runs `build` in every workspace package.
+
+## 3. Start ClickHouse (only for integration tests / examples)
+
+Unit tests do **not** need a server. Integration tests (`npm run test:*:integration*`) and the example runners do.
+
+From the repo root:
+
+```bash
+docker compose up -d
+```
+
+This starts both the single-node setup (`clickhouse` on 8123/9000, `clickhouse_tls` on 8443/9440) and the two-node cluster (`clickhouse1`, `clickhouse2`, plus the `nginx` round-robin entrypoint on 8127). All services use non-overlapping ports so a single `up -d` covers every integration test mode.
+
+To override the server version, set `CLICKHOUSE_VERSION` when starting Compose; for example: `CLICKHOUSE_VERSION=head docker compose up -d`, `CLICKHOUSE_VERSION=latest docker compose up -d`, or `CLICKHOUSE_VERSION=24.8 docker compose up -d` to use an explicit version tag.
+
+## 4. Verify
+
+After the steps above you can run, for example:
+
+- `npm run lint` — lint every workspace package
+- `npm run typecheck` — typecheck every workspace package
+- `npm run test:node:unit` / `npm run test:web:unit` — unit tests, no server required
+- `npm run test:node:integration` / `npm run test:web:integration` — integration tests, server required
+- From `examples/node` or `examples/web`: `npm run lint`, `npm run typecheck`, `npm run run-examples`
+
+See `npm run` from the repo root for the full list of test scripts.

.github/dependabot.yml

@@ -18,10 +18,6 @@ updates:
       dev-dependencies:
         dependency-type: 'development'
     ignore:
-      - dependency-name: 'eslint'
-        versions: ['>= 10']
-      - dependency-name: '@eslint/js'
-        versions: ['>= 10']
       - dependency-name: '@opentelemetry/auto-instrumentations-node'
         versions: ['0.70.0']
       - dependency-name: '@types/node'

.github/workflows/publish.yml

@@ -72,6 +72,9 @@ jobs:
   latest:
     if: github.ref == 'refs/heads/main' && github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write # Required to push the release git tag
+      id-token: write # Required for npm OIDC authentication and provenance
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -86,9 +89,11 @@ jobs:
         run: npm ci
 
       - name: Get the release version
+        id: version
         run: |
           BASE_VERSION=$(node -p "require('./packages/client-common/package.json').version")
           echo "Using version: $BASE_VERSION"
+          echo "version=$BASE_VERSION" >> "$GITHUB_OUTPUT"
 
       - name: Build packages
         run: npm --workspaces run build
@@ -98,3 +103,16 @@ jobs:
           npm --workspaces publish \
             --access public \
             --provenance
+
+      - name: Create and push release git tag
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          if git ls-remote --exit-code --tags origin "refs/tags/${RELEASE_VERSION}" >/dev/null 2>&1; then
+            echo "Tag ${RELEASE_VERSION} already exists on origin; skipping."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "${RELEASE_VERSION}" -m "Release ${RELEASE_VERSION}"
+          git push origin "refs/tags/${RELEASE_VERSION}"

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

@@ -0,0 +1,118 @@
+name: 'upstream-sql-tests'
+
+permissions: {}
+
+on:
+  workflow_dispatch:
+    inputs:
+      upstream_ref:
+        description: 'ClickHouse/ClickHouse ref to check out'
+        required: false
+        default: 'master'
+        type: string
+  schedule:
+    - cron: '0 5 * * *'
+  push:
+    branches:
+      - main
+    paths:
+      - 'tests/clickhouse-test-runner/**'
+      - '.github/workflows/upstream-sql-tests.yml'
+  pull_request:
+    paths:
+      - 'tests/clickhouse-test-runner/**'
+      - '.github/workflows/upstream-sql-tests.yml'
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.ref }}'
+  cancel-in-progress: true
+
+env:
+  UPSTREAM_REPO: 'ClickHouse/ClickHouse'
+
+jobs:
+  upstream-sql-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        clickhouse: [head, latest]
+        # Round-robin shards keep each job at roughly one minute so the
+        # upstream SQL tests no longer dominate PR CI runtime. Bump
+        # `shard` and `SHARD_TOTAL` together if the allowlist grows enough
+        # that per-shard runtime climbs back above ~1 minute.
+        shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+    steps:
+      - name: Checkout clickhouse-js
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Checkout ClickHouse upstream
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: ${{ env.UPSTREAM_REPO }}
+          ref: ${{ github.event.inputs.upstream_ref || 'master' }}
+          path: tests/clickhouse-test-runner/.upstream/ClickHouse
+          sparse-checkout: |
+            tests/clickhouse-test
+            tests/queries
+            tests/config
+            tests/ci
+            tests/performance
+            docker/test/util
+          fetch-depth: 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+
+      - name: Setup Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.12'
+
+      - name: Install Python dependencies for upstream clickhouse-test
+        run: |
+          python -m pip install --upgrade pip
+          pip install jinja2
+
+      - 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: Build test runner
+        working-directory: tests/clickhouse-test-runner
+        run: |
+          npm install
+          npm run build
+
+      - name: Make upstream test script executable
+        run: |
+          chmod +x tests/clickhouse-test-runner/.upstream/ClickHouse/tests/clickhouse-test
+
+      - name: Run upstream SQL tests
+        id: run-tests
+        env:
+          CLICKHOUSE_CLIENT_CLI_LOG: ${{ github.workspace }}/upstream-run.log
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 10
+        run: |
+          bash tests/clickhouse-test-runner/scripts/run-upstream-tests.sh --no-stateful
+
+      - name: Upload test artifacts
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: upstream-sql-tests-${{ matrix.clickhouse }}-shard-${{ matrix.shard }}
+          retention-days: 14
+          if-no-files-found: ignore
+          path: |
+            upstream-run.log
+            tests/clickhouse-test-runner/.upstream/ClickHouse/tests/queries/**/*.stdout
+            tests/clickhouse-test-runner/.upstream/ClickHouse/tests/queries/**/*.stderr
+            tests/clickhouse-test-runner/.upstream/ClickHouse/tests/queries/**/*.diff

AGENTS.md

@@ -12,13 +12,13 @@
    }
    ```
 
-2. When adding new log messages with suggestions for users, make sure to create a unique documentation page in the `docs` directory with a detailed explanation of the issue and how to resolve it. Then, include a link to that documentation page in the log message. For example:
+2. When adding new log messages with suggestions for users, make sure to create a unique documentation page under the `docs/` directory (use `docs/howto/` for task-style guides; see `docs/socket_hang_up_econnreset.md` as a reference) with a detailed explanation of the issue and how to resolve it. Then, include a link to that documentation page in the log message. For example:
 
    ```ts
    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/example-log-message.md',
+         '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',
      })
    }
    ```
@@ -49,7 +49,8 @@ The goals of the refactor are:
    - `coding/` — day-to-day client API usage (configure, ping, basic insert/select, parameter
      binding, sessions, data types, custom JSON).
    - `performance/` — async inserts, streaming with backpressure, file/Parquet streams, progress
-     streaming, server-side bulk moves. Node-only (no `performance/` folder under `examples/web`).
+     streaming, server-side bulk moves. Mostly Node-only; `examples/web/performance/` exists for the
+     few perf scenarios that work in the browser (e.g. streaming `JSONEachRow`).
    - `troubleshooting/` — cancellation, timeouts, long-running query progress, server error surfaces,
      number-precision pitfalls.
    - `security/` — TLS, RBAC, SQL-injection-safe parameter binding.
@@ -61,6 +62,42 @@ The goals of the refactor are:
    a duplicated example, update **all** copies. The current duplicates and their primary locations
    are listed in [`examples/README.md`](examples/README.md#editing-duplicated-examples).
 
+## Skills
+
+- Each shipped skill must also be listed in the `agents.skills` array of
+  [`packages/client-node/package.json`](packages/client-node/package.json) so downstream tooling can
+  discover it. The [`Skills E2E`](.github/workflows/e2e-skills.yml) workflow
+  (`tests/e2e/skills/check.js`) asserts that the packaged tarball contains the declared skills.
+
+## Embedded docs
+
+The [`docs/`](docs) directory holds long-form troubleshooting / how-to pages that log messages and
+skill references can link to (e.g. `docs/socket_hang_up_econnreset.md`, `docs/howto/`). Prefer
+adding new pages here over linking out to external docs from log messages.
+
+## Upstream SQL test harness
+
+The [`tests/clickhouse-test-runner`](tests/clickhouse-test-runner) harness is a Node.js port of `clickhouse-client` that allows the official ClickHouse Python test runner (`tests/clickhouse-test`) to drive a subset of the upstream SQL test suite against `@clickhouse/client`.
+
+### 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 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.
+
+See [`tests/clickhouse-test-runner/README.md`](tests/clickhouse-test-runner/README.md) for build, usage, and environment-variable documentation. When harness behavior changes (new wrapper flags, new short-circuited keys in `bin/clickhouse`, new entries in the settings allowlists), review the README and [`.github/workflows/upstream-sql-tests.yml`](.github/workflows/upstream-sql-tests.yml) to keep them in sync with the implementation.
+
+### Strategy for growing the allowlist
+
+The allowlist is grown in **batches of ~100 candidate tests at a time**, in upstream filename order, following this loop:
+
+1. **Pre-filter the candidate batch.** Skip non-SQL tests (`.sh`, `.py`, `.j2`) and tests tagged for unsupported infrastructure (`shard`, `distributed`, `replicated`, `zookeeper`, `kafka`, `s3`, `mysql`, `tls`, etc.). These will never pass through this harness as it stands today.
+2. **Run each candidate through the harness** with `--no-stateful --no-long`. **Only keep tests that report `[ OK ]`**; drop failures and skips.
+3. **Validate against the CI matrix before committing**, not just one local server version. The CI workflow runs `{ClickHouse latest, head} × {shard 1..N}` — a test that passes locally on `head` may fail on `latest` (or vice versa) and break CI.
+4. **Beware substring/prefix expansion.** `tests/clickhouse-test` treats positional arguments as **substring/prefix matches** rather than exact names, so an allowlist entry like `00396_uuid` will silently pull in `00396_uuid_v7`, `00712_prewhere_with_alias` will pull in `00712_prewhere_with_alias_bug_2`, etc. When adding an entry whose name is a prefix of any other test in `0_stateless`, prefer the longest unambiguous form, or accept that the siblings come along and verify they all pass.
+5. **Prune flakes promptly.** If a previously-passing test starts to flake on the nightly run, remove it (or its prefix-expanded siblings) from the allowlist rather than retrying — the allowlist exists to be a stable green signal, not a TODO list.
+
 ## When reviewing code changes
 
 For every pull request review, make sure to provide an evaluation of the following aspects:
@@ -75,6 +112,6 @@ For every pull request review, make sure to provide an evaluation of the followi
 
 1. When reviewing code changes, it is important to consider the impact on the API quality and stability. For example, if the code changes involve modifying the library's public API surface (such as exported functions, classes, or types) or adding new public APIs, it is important to ensure that the changes are well-documented and do not break existing functionality for users of the library.
 
-2. When introducing new features or making changes to the API make sure to update the CHANGELOG.md file with a concise description of the changes followed with an example usage if applicable.
+2. When introducing new features or making changes to the API, make sure the PR description includes a concise, human-readable CHANGELOG entry (followed by an example usage if applicable) so it can be folded into `CHANGELOG.md` at release time. This matches the PR template checklist item ("A human-readable description of the changes was provided to include in CHANGELOG").
 
 3. Additionally, make sure that the official documentation is in sync with the changes.