ClickHouse Upgrade & Migration

Overview

Safely upgrade ClickHouse server and the

@clickhouse/client

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';
const client = createClient({
  host: 'http://localhost:8123',
});

// After (v1.x)
const client = createClient({
  url: 'http://localhost:8123',   // 'host' renamed to 'url'
});

// v0.x → v1.x: query result handling
// Before: rs.json() returned { data: [...], statistics: {...} }
// After: rs.json() returns the rows array directly

// Before
const result = await rs.json();
const rows = result.data;

// After
const rows = await rs.json();

Step 4: Upgrade ClickHouse Server

ClickHouse Cloud: Upgrades happen automatically. Check release notes in the Cloud console.

Self-hosted upgrade procedure:

# 1. Backup current data
clickhouse-client --query "BACKUP DATABASE analytics TO Disk('backups', 'pre-upgrade')"

# 2. Check compatibility
clickhouse-client --query "SELECT * FROM system.settings WHERE changed"

# 3. Stop server gracefully
sudo systemctl stop clickhouse-server

# 4. Update packages
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install clickhouse-server clickhouse-client

# 5. Start and verify
sudo systemctl start clickhouse-server
clickhouse-client --query "SELECT version()"

# 6. Check for schema issues
clickhouse-client --query "
    SELECT database, table, engine, metadata_modification_time
    FROM system.tables WHERE database NOT IN ('system', 'INFORMATION_SCHEMA')
"

Step 5: Validate After Upgrade

// Post-upgrade validation script
import { createClient } from '@clickhouse/client';

const client = createClient({ url: process.env.CLICKHOUSE_HOST! });

async function validateUpgrade() {
  const checks = [
    { name: 'ping', fn: () => client.ping() },
    { name: 'version', fn: async () => {
      const rs = await client.query({ query: 'SELECT version()', format: 'JSONEachRow' });
      return rs.json();
    }},
    { name: 'schema', fn: async () => {
      const rs = await client.query({
        query: 'SELECT database, name, engine FROM system.tables WHERE database = {db:String}',
        query_params: { db: 'analytics' },
        format: 'JSONEachRow',
      });
      return rs.json();
    }},
    { name: 'insert', fn: async () => {
      await client.insert({
        table: 'analytics.events',
        values: [{ event_type: 'upgrade_test', user_id: 0, payload: '{}' }],
        format: 'JSONEachRow',
      });
      return { success: true };
    }},
    { name: 'query', fn: async () => {
      const rs = await client.query({
        query: 'SELECT count() AS cnt FROM analytics.events',
        format: 'JSONEachRow',
      });
      return rs.json();
    }},
  ];

  for (const check of checks) {
    try {
      const result = await check.fn();
      console.log(`[PASS] ${check.name}:`, JSON.stringify(result));
    } catch (err) {
      console.error(`[FAIL] ${check.name}:`, (err as Error).message);
    }
  }
}

validateUpgrade();

Step 6: Rollback Procedure

# Node.js client rollback
npm install @clickhouse/client@<previous-version> --save-exact

# Server rollback (self-hosted)
sudo systemctl stop clickhouse-server
sudo apt-get install clickhouse-server=<previous-version>
sudo systemctl start clickhouse-server

# Restore from backup if needed
clickhouse-client --query "RESTORE DATABASE analytics FROM Disk('backups', 'pre-upgrade')"

Version Compatibility Matrix

url

host

Error Handling

Unknown setting

Cannot parse datetime

Method not found

Checksum mismatch

Resources

• Client Releases
• Server Changelog
• Cloud Upgrades

Next Steps

For CI/CD integration, see

clickhouse-ci-integration