用途：安全升级 ClickHouse 服务器与 @clickhouse/client Node.js SDK，包含回滚流程与破坏性变更检测。整体工作流为：检查版本 → 审阅变更日志 → 升级客户端 → 升级服务器 → 验证 → 必要时回滚。完整命令序列见 references/implementation.md，可运行的迁移、验证与回滚代码见 references/examples.md。
前提条件：已知当前 ClickHouse 版本（SELECT version()）；使用 Git 做版本控制（客户端改动落在 upgrade/ 分支）；具备集成验证用测试套件（npm test）；有预生产测试的 staging 环境；已设置 CLICKHOUSE_HOST 及凭据。
认证：客户端与验证脚本从 CLICKHOUSE_HOST 环境变量读取服务器 URL（如本地 http://localhost:8123 或 ClickHouse Cloud 端点）。凭据保存在环境变量中，切勿硬编码：向 createClient 传入 process.env.CLICKHOUSE_USER / CLICKHOUSE_PASSWORD；原始 curl 通过 X-ClickHouse-User / X-ClickHouse-Key 头传递。ClickHouse Cloud 端点要求 TLS（https://）和密码；自托管默认安装常在 8123（HTTP 端口）上开放，仅限开发环境。
主要步骤：1）检查当前版本，记录服务器版本、已安装客户端版本与最新发布版本作为回滚基线，命令如 curl 'http://localhost:8123/?query=SELECT+version()'、npm list @clickhouse/client、npm view @clickhouse/client version。2）审阅变更日志，注意 createClient 选项重命名、默认设置变化（压缩、超时）、查询结果格式行为、移除的 SQL 函数、重命名的 MergeTree 设置。3）升级 Node.js 客户端，在独立分支上操作：git checkout -b upgrade/clickhouse-client、npm install @clickhouse/client@latest、npm test，再应用代码迁移模式（host → url 选项重命名、rs.json() 结果结构变化）。4）升级 ClickHouse 服务器：Cloud 自动升级，只需阅读控制台发布说明；自托管按固定顺序：备份 → 检查变更设置 → 停止 → apt-get install → 启动 → 验证版本 → 扫描 schema。5）升级后验证：运行验证脚本，执行 ping、版本、schema、插入、查询检查，各自报告 PASS/FAIL。6）回滚：若验证失败，回滚客户端（用 --save-exact 安装先前版本）、服务器包，若数据受影响则从升级前备份 RESTORE。
版本兼容矩阵：1.x 客户端需服务器 22.6+、Node.js 18+，稳定 API，使用 url 选项；0.3.x 需服务器 22.6+、Node.js 16+，使用 host 选项，JSON 结果结构不同；0.2.x 需服务器 21.8+、Node.js 14+，为初始版本。
输出：记录当前与目标版本作为回滚基线；客户端在隔离分支升级且 npm test 通过；代码已按已知破坏性变更迁移；服务器按备份→停止→安装→验证顺序升级；升级后验证全部 PASS；为客户端与服务器记录回滚路径。
错误处理：未知设置（配置新默认值）→ 移除废弃设置；无法解析 datetime（格式变化）→ 更新日期格式字符串；方法未找到（客户端 API 变化）→ 查阅迁移指南；校验和不匹配（升级损坏）→ 回滚并重新下载。
限制：资料未提供具体收费、价格或平台支持范围等信息。