| name | clickhouse-upgrade-migration |
| description | Use when upgrading ClickHouse server versions or the @clickhouse/client SDK,
handling breaking changes between versions, or migrating from older client
libraries — covers version checks, changelog review, staged upgrade, post-upgrade
validation, and rollback.
Trigger with phrases like "upgrade clickhouse", "clickhouse version upgrade",
"update clickhouse client", "clickhouse breaking changes", "new clickhouse version".
|
| allowed-tools | Read, Edit, Bash(npm:*), Bash(git:*) |
| version | 1.7.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","database","analytics","clickhouse","olap"] |
| compatibility | Designed for Claude Code |
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
npm list @clickhouse/client
npm view @clickhouse/client version
