clickhouse-upgrade-migration

name	clickhouse-upgrade-migration
description	Upgrade ClickHouse server versions and @clickhouse/client SDK safely. Use when upgrading ClickHouse, handling breaking changes between versions, or migrating from older client libraries. Trigger: "upgrade clickhouse", "clickhouse version upgrade", "update clickhouse client", "clickhouse breaking changes", "new clickhouse version".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(git:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","database","analytics","clickhouse","olap"]
compatible-with	claude-code

ClickHouse Upgrade & Migration

Overview

Safely upgrade ClickHouse server and the @clickhouse/client Node.js SDK, with rollback procedures and breaking change detection.

Prerequisites

• Current ClickHouse version known (SELECT version())
• Git for version control
• Test suite for integration validation
• Staging environment for pre-production testing

Instructions

Step 1: Check Current Versions

# Check server version (via HTTP)
curl 'http://localhost:8123/?query=SELECT+version()'

# Check Node.js client version
npm list @clickhouse/client

# Check latest available
npm view @clickhouse/client version

-- Server-side version details
SELECT
    version()           AS server_version,
    uptime()            AS uptime_sec,
    currentDatabase()   AS current_db;

Step 2: Review Changelog

# View release notes
open https://github.com/ClickHouse/clickhouse-js/releases

# Server changelog
open https://github.com/ClickHouse/ClickHouse/blob/master/CHANGELOG.md

Key breaking changes to watch for:

• Client API signature changes (createClient options)
• Default setting changes (compression, timeouts)
• New query result format behavior
• Deprecated SQL functions removed in server upgrades
• MergeTree settings renamed or defaults changed

Step 3: Upgrade the Node.js Client

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

Common migration patterns:

// v0.x → v1.x: createClient options restructured
// Before (v0.x)
import { createClient } from '@clickhouse/client';
 client = ({
  : ,
});


 client = ({
  : ,   
});






 result =  rs.();
 rows = result.;


 rows =  rs.();