Summary

Ports ClickHouse/clickhouse-java/tests/clickhouse-client to this repo as tests/clickhouse-test-runner/, a small Node CLI that wraps @clickhouse/client to mimic the upstream clickhouse-client binary. With it on PATH, the official tests/clickhouse-test runner will exercise the JS client against the core ClickHouse SQL test suite.

• Standalone package (tests/clickhouse-test-runner/, not a workspace, only depends on @clickhouse/client) with its own tsconfig, eslint, and Vitest config.
• bin/clickhouse bash shim — short-circuits extract-from-config --key listen_host → 127.0.0.1 (the only key the upstream runner needs), otherwise exec node dist/main.js.
• Two backends selected via CLICKHOUSE_CLIENT_CLI_IMPL (mirrors Java's client/jdbc split):
  • client (default) — client.exec({ query, clickhouse_settings: { default_format: 'TabSeparated', ... } }) with the response stream piped straight to stdout (raw bytes, no decoding).
  • http — Node fetch against /?default_format=TabSeparated&... with basic auth, body-streamed to stdout with backpressure.
• Arg parser (src/args.ts) accepting both --foo bar and --foo=bar, dashed/underscored variants listed as separate canonical entries in BASE_OPTIONS, short forms (-h/-u/-d/-q/-s/-n), and dynamic long options. Unknown long options are classified against SERVER/CLIENT_ONLY allowlists copied from the Java port: server settings are forwarded, client-only and unknown are silently dropped. Per review feedback, max_threads was reclassified from CLIENT_ONLY_SETTINGS to SERVER_SETTINGS so --max_threads=N from the upstream test runner is forwarded to ClickHouse instead of being silently dropped. The unused aliases field on OptionSpec was removed since the parser never read it (dash/underscore forms work via separate BASE_OPTIONS entries).
• Quote-aware multi-query splitter (src/split-queries.ts) — tracks single/double/backtick state and \-escapes; only splits on unquoted ;.
• Logging to CLICKHOUSE_CLIENT_CLI_LOG (default /tmp/clickhouse-client-cli.log) with CWD fallback; failures are swallowed so the CLI never breaks tests.
• Exit codes via process.exitCode only — never process.exit() — to avoid truncating stdout writes.
• Vitest unit tests for split-queries, args, extract-from-config, and log. Live smoke against docker compose up -d clickhouse exercises both backends and --multiquery over stdin.

Usage:

cd tests/clickhouse-test-runner && npm install && npm run build

# Drive the upstream runner (download CH test files; do NOT clone the full repo)
CLICKHOUSE_CLIENT_CLI_LOG=./test-run.log \
  PATH="$PWD/tests/clickhouse-test-runner/bin:$PATH" \
  /path/to/ClickHouse/tests/clickhouse-test 01428_hash_set_nan_key

The SERVER/CLIENT_ONLY allowlists are copied from the Java port and will need periodic resync as ClickHouse adds settings.

Checklist

• Unit and integration tests covering the common scenarios were added