Agent skill · software engineering · jeremylongshore
clickhouse-upgrade-migration
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".
Why this skill is useful
Adds specific command sequences and rollback procedures for ClickHouse upgrades that the AI wouldn't reliably generate on its own.
What it needs
Requires git, npm installed locally. About 4k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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 CLICKHOUSEHOST set (and credentials — see Authentication) Authentication The client and validation scripts read the server URL from the CLICKHOUSEHOST 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. 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. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/clickhouse-upgrade-migration