clickhouse-upgrade-migration

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 <[e-mail]>
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 'http://localhost:8123/?query=SELECT+version()'   # server
npm list @clickhouse/client                            # installed client
npm view @clickhouse/client version                    # latest available