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.CLICKHOUSEUSER / CLICKHOUSEPASSWORD, 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

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

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

• Client Releases
• Server Changelog
• ClickHouse Cloud Upgrades

Next Steps

For CI/CD integration of the upgraded client, see clickhouse-ci-integration.

For pre-production release gating, see clickhouse-prod-checklist.