ClickHouse Upgrade & Migration

Overview

Safely upgrade ClickHouse server and the @clickhouse/client Node.js SDK, with rollback procedures and breaking-change detection. The workflow is check versions → review changelogs → upgrade the client → upgrade the server → validate → rollback if needed. Full command sequences live in references/implementation.md; the runnable migration, validation, and rollback code lives in references/examples.md.

Prerequisites

Current ClickHouse version known (SELECT version())
Git for version control (client changes land on an upgrade/ branch)
Test suite for integration validation (npm test)
Staging environment for pre-production testing
CLICKHOUSE_HOST set (and credentials — see Authentication)

Authentication

The client and validation scripts read the server URL from the CLICKHOUSE_HOST environment variable (e.g. http://localhost:8123 locally, or your ClickHouse Cloud endpoint). Keep credentials in the environment, never hardcoded: pass username / password to createClient from process.env.CLICKHOUSE_USER / CLICKHOUSE_PASSWORD, and for raw curl send them via the X-ClickHouse-User / X-ClickHouse-Key headers. ClickHouse Cloud endpoints require TLS (https://) and a password; self-hosted default installs often run open on 8123 (the HTTP port) in dev only.

Instructions

Work the steps in order — the client upgrade and the server upgrade are separate, independently reversible changes. Read references/implementation.md for the full command sequence of each step.

Step 1: Check Current Versions

Capture the server version, the installed client version, and the latest published client before changing anything — this is your rollback target.

curl 'http://localhost:8123/?query=SELECT+version()'   # server
npm list @clickhouse/client                            # installed client
npm view @clickhouse/client version                    # latest available

Step 2: Review Changelog

Read the client and server changelogs and note breaking changes: createClient option renames, default setting changes (compression, timeouts), query result-format behavior, removed SQL functions, and renamed MergeTree settings. Full checklist and links: implementation.md Step 2.

Step 3: Upgrade the Node.js Client

Isolate the client bump on a branch so it is reversible independent of the server.

git checkout -b upgrade/clickhouse-client
npm install @clickhouse/client@latest
npm test

Then apply the code-migration patterns (the host → url option rename and the rs.json() result-shape change) — full before/after in references/examples.md under "Common migration patterns". Edit the client-initialization and result-handling code to match.

Step 4: Upgrade ClickHouse Server

ClickHouse Cloud upgrades automatically — just read the console release notes. Self-hosted follows a fixed sequence: backup → check changed settings → stop → apt-get install → start → verify version → scan schema. Full command block: implementation.md Step 4.

Step 5: Validate After Upgrade

Run the post-upgrade validation script — ping, version, schema, insert, and query checks, each reporting PASS/FAIL. Full script: references/examples.md under "Post-upgrade validation script".

Step 6: Rollback Procedure

If validation fails, roll back the client (npm install the previous version with --save-exact), the server package, and — if data is affected — RESTORE from the pre-upgrade backup. Full commands: references/examples.md under "Rollback commands".

Version Compatibility Matrix

Client Version	Min Server Version	Node.js	Key Changes
1.x	22.6+	18+	Stable API, `url` option
0.3.x	22.6+	16+	`host` option, different JSON result shape
0.2.x	21.8+	14+	Initial release

Output

Current and target versions recorded (server + client) as the rollback baseline
Client upgraded on an isolated upgrade/ branch with npm test green
Code migrated for known breaking changes (host → url, rs.json() shape)
Server upgraded via the backup → stop → install → verify sequence
Post-upgrade validation run: ping, version, schema, insert, and query all PASS
Documented rollback path for both client and server if any check fails

Error Handling

Issue	Cause	Solution
`Unknown setting`	New default in config	Remove deprecated setting
`Cannot parse datetime`	Format change	Update date format strings
`Method not found`	Client API changed	Check migration guide
`Checksum mismatch`	Corrupted upgrade	Rollback and re-download

Examples

Two ready-to-run starting points live in references/examples.md:

Common migration patterns — before/after for the createClient option rename and the rs.json() result-shape change between v0.x and v1.x.
Post-upgrade validation script — a self-contained check runner that exercises ping → version → schema → insert → query.

// Validation entry point — full runner in references/examples.md
const client = createClient({ url: process.env.CLICKHOUSE_HOST! });
await client.ping();                                          // 1. reachable
await client.query({ query: 'SELECT version()', format: 'JSONEachRow' }); // 2. new version live
// 3. schema, insert, and query checks follow in the full script

Resources

Next Steps

For CI/CD integration of the upgraded client, see clickhouse-ci-integration. For pre-production release gating, see clickhouse-prod-checklist.