clickhouse-js-node-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ClickHouse Node.js Client Troubleshooting

ClickHouse Node.js客户端故障排查

Reference: https://clickhouse.com/docs/integrations/javascript

⚠️ Node.js runtime only. This skill covers the
@clickhouse/client
package running in a Node.js runtime exclusively — including Next.js Node runtime API routes, React Server Components, Server Actions, and standard Node.js processes. Do not apply this skill to browser client components, Web Workers, Next.js Edge runtime, Cloudflare Workers, or any usage of
@clickhouse/client-web
. For browser/edge environments, the correct package is
@clickhouse/client-web
.

参考文档：https://clickhouse.com/docs/integrations/javascript

⚠️ 仅适用于Node.js运行时。 本技能仅涵盖在Node.js运行时中运行的
@clickhouse/client
包——包括Next.js Node运行时API路由、React Server Components、Server Actions以及标准Node.js进程。请勿将本技能应用于浏览器客户端组件、Web Workers、Next.js Edge运行时、Cloudflare Workers或任何
@clickhouse/client-web
的使用场景。对于浏览器/边缘环境，正确的包是
@clickhouse/client-web
。

How to Use This Skill

如何使用本技能

Identify the issue — match symptoms to the Issue Index below and read the corresponding reference file.
Lead with the diagnosis — explain what's likely causing the issue before giving the fix.
Note version constraints — flag if a fix requires a minimum client version and check it against what the user provided.
Ask only what's missing — if the fix is version-dependent and you don't know their version, ask; otherwise help immediately.

识别问题——将症状与下方的问题索引匹配，并阅读对应的参考文档。
先诊断后修复——在提供解决方案前，先解释可能导致问题的原因。
注意版本限制——如果修复需要最低客户端版本，请标记出来并与用户提供的版本进行核对。
仅询问必要信息——如果修复依赖版本但你不知道用户的版本，再进行询问；否则直接提供帮助。

Issue Index

问题索引

Identify the user's issue from the list below and read the corresponding reference file for detailed troubleshooting steps.

Issue	Symptoms	Reference file
Socket Hang-Up / ECONNRESET	`socket hang up` , `ECONNRESET` , intermittent connection drops, long-running queries timing out	`reference/socket-hangup.md`
Data Type Mismatches	Large integers returned as strings, decimal precision loss, Date/DateTime insertion failures	`reference/data-types.md`
Read-Only User Errors	Errors when using response compression with `readonly=1` users	`reference/readonly-users.md`
Proxy / Pathname URL Confusion	Wrong database selected, requests failing behind a proxy with a path prefix	`reference/proxy-pathname.md`
TLS / Certificate Errors	TLS handshake failures, certificate verification issues, mutual TLS setup	`reference/tls.md`
Compression Not Working	GZIP compression not activating for requests or responses	`reference/compression.md`
Logging Not Showing Anything	No log output, need custom logger integration	`reference/logging.md`
Query Parameters Not Interpolated	Parameterized queries not working, SQL injection concerns	`reference/query-params.md`

从下方列表中识别用户的问题，并阅读对应的参考文档获取详细的故障排查步骤。

问题	症状	参考文档
Socket Hang-Up / ECONNRESET	`socket hang up` 、 `ECONNRESET` 、连接间歇性断开、长时间查询超时	`reference/socket-hangup.md`
数据类型不匹配	大整数以字符串形式返回、小数精度丢失、Date/DateTime插入失败	`reference/data-types.md`
只读用户错误	使用 `readonly=1` 用户时启用响应压缩出现错误	`reference/readonly-users.md`
代理/路径URL混淆	选错数据库、带路径前缀的代理后请求失败	`reference/proxy-pathname.md`
TLS / Certificate Errors	TLS握手失败、证书验证问题、双向TLS配置	`reference/tls.md`
压缩功能失效	请求或响应未激活GZIP压缩	`reference/compression.md`
无日志输出	没有日志输出，需要集成自定义日志器	`reference/logging.md`
查询参数未插值	参数化查询失效、存在SQL注入风险	`reference/query-params.md`