功能描述

ClickHouse cluster migration planner. Use when planning data migration between ClickHouse clusters, including cross-cluster migrations, horizontal scaling, d...

使用说明 (SKILL.md)

ClickHouse Sync Plan (cksync-plan)

Name: Alibabacloud Cksync Plan
Author: sdk-team

A skill for planning ClickHouse cluster data migration solutions, including migration plans, risks, and considerations.

When to Use

Data migration between different ClickHouse clusters
Horizontal scaling (adding/removing nodes) for ClickHouse clusters
Disk downgrade operations
Cross-availability zone migrations
Upgrading to multi-replica, multi-AZ deployments

Workflow

Step 1: Gather Source Cluster Information

Ask user for source cluster type:

Self-built ClickHouse or non-Alibaba Cloud ClickHouse
Alibaba Cloud ClickHouse Community Edition
Alibaba Cloud ClickHouse Enterprise Edition

Ask user for source cluster version (e.g., 20.8, 22.8, 23.8, 24.3):

Version affects migration method compatibility
BACKUP/RESTORE requires ≥22.8
Incremental cksync migration requires target ≥20.8

Step 2: Gather Target Cluster Information

Ask user for target cluster type:

Alibaba Cloud ClickHouse Community Edition
Alibaba Cloud ClickHouse Enterprise Edition
To be determined

Step 3: Collect Cluster Details (REQUIRED)

This step is mandatory. You MUST collect database and table information before proceeding to migration plan selection.

Required Information

Database list with engines
Table list with engines, partition counts, data sizes, and write speeds

Option A: User Executes SQL

Provide SQL queries from references/sql.md section 1 for user to execute:

Database Information - Query system.databases for database names and engines
Table Information - Comprehensive query including table names, engines, engine_full (for TTL), partition counts, data sizes, and write speeds

Key fields to collect:

engine_full: Contains TTL clause (e.g., TTL event_time + INTERVAL 7 DAY)
part_count: Partition count per table
data_bytes: Data size per shard
write_speed_bytes_per_sec: Write speed calculated from part_log

For complete SQL queries, see references/sql.md section 1.

Option B: Direct Query via HTTP

Request connection details from user:

HOST_NAME: Cluster endpoint (e.g., cc-xxx.clickhouse.rds.aliyuncs.com)
HTTP_PORT: HTTP port (default: 8123)
USER_NAME: Database username
PASSWORD: Database password

Use secure credential handling and HTTP query examples from references/sql.md section 5.

Analysis Checklist

After collecting data, verify:

Required metadata is complete (database engine, table engine, engine_full, partitions, data size, write speed)
Migration compatibility checks are completed using references/plans.md (method-specific conditions)
Version and read-only window constraints are mapped to candidate methods
Risks and mitigations are identified and recorded in the plan

Step 4: Business Requirements

Ask for allowed read-only time:

0 minutes
Within 30 minutes
Within 1 day
Not sure yet

Step 5: Select and Present Migration Plan

Based on gathered information, analyze and recommend from these migration methods:

Method	Best For	Min Read-Only Time
Console (cksync)	Most migrations to Alibaba Cloud	~10 min
BACKUP/RESTORE	Large data, same edition type, version ≥22.8	Varies by data size
INSERT FROM REMOTE	Flexible control, small-medium data	~10 min per batch
Business Double-Write	Zero downtime required	0
Kafka Double-Write	Existing Kafka pipelines or business writes switched to Kafka	0
Big Cluster Federation	Large scale, complex scenarios	0

Hard requirement: MUST output a plan, never output empty content.

Even when information is incomplete, you MUST output a provisional migration plan. The provisional plan must include:

assumptions used,
missing-information checklist,
confidence level and key uncertainties,
next steps to finalize recommendation after user provides missing inputs.

Migration Methods Overview

1. Console (cksync) Migration

Default choice for most Alibaba Cloud migration scenarios, especially in-place operations. For support boundaries, engine constraints, TTL/write-speed checks, merge risk, and resource prerequisites, see references/plans.md section 1.

2. BACKUP/RESTORE Migration

Suitable for same-edition migrations where full backup/restore workflow is acceptable. For version/edition constraints, supported engines, command patterns, and progress monitoring, see references/plans.md section 2.

3. INSERT FROM REMOTE Migration

Best when fine-grained table/partition/time-range control is needed. For applicability boundaries and operational constraints, see references/plans.md section 3. For SQL templates and detailed steps, see references/sql.md section 2.

4. Business Double-Write

Use when zero downtime is required and application-side dual-write is feasible. For detailed conditions, see references/plans.md section 4.

5. Kafka Double-Write

Use when dual-consumer switchover via Kafka is feasible, including both existing Kafka pipelines and cases where business writes can be switched to Kafka first. For detailed conditions, see references/plans.md section 5.

6. Big Cluster Federation

Advanced option for large/complex migrations with strong business and technical collaboration.

Community + Enterprise: See references/big-cluster-community-enterprise.md
Self-built + Cloud: See references/big-cluster-self-built-community.md

Output Format

Default deliverable: Produce one migration plan only. Structure it using assets/migration-plan-template.md and include the key sections below (cluster facts and commands may appear inline in the plan; that counts as the single deliverable).

Additional files only on request: Do not create separate files for cluster-information documentation, scripts, or SQL unless the customer explicitly asks for them. When they do, use assets/cluster-info-template.md for cluster documentation and place scripts/SQL in clearly named files as requested.

Key sections in the migration plan:

Executive Summary - Method, data size, duration, downtime
Source Cluster Analysis - Databases, tables, compatibility check
Migration Method Selection - Rationale and alternatives
Migration Steps - Pre/execution/post with commands
Risks & Mitigations - With probability and impact
Rollback Plan - Trigger conditions and steps
Timeline - Phase schedule with owners
Reference Links - Documentation URLs

Method Selection Reference

For quick scenario-to-method mapping and method-specific constraints (including in-place migration priority and Enterprise → Enterprise options), see references/plans.md section "Method Selection Priority" and related method sections.

Additional Resources

references/plans.md - Detailed migration plan conditions
references/sql.md - SQL templates and commands
references/stop-merge-storm.md - How to stop post-sync merge storm
references/big-cluster-community-enterprise.md - Community + Enterprise federation
references/big-cluster-self-built-community.md - Self-built + Cloud federation

安全使用建议

This skill is a documentation / planner tool and appears coherent. Before using it: (1) do not paste plaintext DB passwords into chat; prefer pasting query results or run the provided SQL locally and paste outputs, or follow the skill's secure suggestions (env vars or ~/.netrc) when running curl locally; (2) be aware the skill's template mandates always producing a plan — if you receive a provisional plan, check the assumptions and supply missing metadata before running migration steps; (3) the skill provides operational SQL and config snippets (including commands that modify cluster config and user credentials). Only execute those on systems you control and after peer review; (4) if you want the agent to execute queries on your behalf, treat that as a separate explicit action and never share long-lived credentials in chat. Overall the package is internally consistent with its purpose.

功能分析

Type: OpenClaw Skill Name: alibabacloud-cksync-plan Version: 0.0.1 The alibabacloud-cksync-plan skill bundle is a specialized tool designed to assist users in planning ClickHouse cluster migrations. It provides a comprehensive workflow for gathering cluster metadata and generating migration plans using various methods like cksync, BACKUP/RESTORE, and INSERT FROM REMOTE. While the skill includes instructions for the agent to request database credentials (SKILL.md and references/sql.md) to facilitate metadata collection via HTTP, it emphasizes secure handling practices such as using environment variables or .netrc files. There is no evidence of malicious intent, data exfiltration, or unauthorized execution; the logic is entirely focused on providing administrative guidance and SQL templates for legitimate database migration tasks.

能力评估

✓ Purpose & Capability

Name/description (ClickHouse migration planner) match the included files (SQL templates, migration plans, operational guides). The skill is instruction-only and does not request unrelated cloud credentials, binaries, or config paths.

✓ Instruction Scope

SKILL.md and asset files stay within migration planning: they instruct collecting cluster metadata, running SQL queries (templates provided), and producing migration plans. The skill recommends asking the user for DB connection details if the user chooses direct querying; it does not instruct exfiltration or contact with unknown external endpoints.

✓ Install Mechanism

No install spec or code is included; this is instruction-only, so nothing is downloaded or written to disk by the skill itself.

✓ Credentials

Registry metadata declares no required env vars or credentials. The instructions correctly ask for cluster credentials only as user-supplied inputs (or suggest secure local env/netrc methods) which is proportionate to gathering database metadata.

✓ Persistence & Privilege

Skill is not always-enabled and does not request persistent privileges or modify other skills. It is allowed to be invoked autonomously by default (platform normal) but contains no instructions that require persistent system presence.

版本历史

v0.0.1

Initial release of alibabacloud-cksync-plan - Provides an end-to-end planner for ClickHouse cluster data migrations, covering cross-cluster, scaling, disk, and zone migrations, including self-built to Alibaba Cloud scenarios. - Guides users through required data collection (database/table details, cluster types/versions) before selection of migration methods. - Recommends migration plans with rationale, risks, rollback steps, and timelines; always outputs a plan even when inputs are incomplete (with provisional analysis). - Supports multiple migration strategies including cksync, BACKUP/RESTORE, INSERT FROM REMOTE, business double-write, Kafka, and large cluster federation. - Adheres to a single-plan deliverable format, with supplementary files/scripts only upon user request.

元数据

Slug alibabacloud-cksync-plan

版本 0.0.1

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 1

常见问题

Alibabacloud Cksync Plan 是什么？

ClickHouse cluster migration planner. Use when planning data migration between ClickHouse clusters, including cross-cluster migrations, horizontal scaling, d... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 111 次。

如何安装 Alibabacloud Cksync Plan？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install alibabacloud-cksync-plan」即可一键安装，无需额外配置。

Alibabacloud Cksync Plan 是免费的吗？

是的，Alibabacloud Cksync Plan 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

Alibabacloud Cksync Plan 支持哪些平台？

Alibabacloud Cksync Plan 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 Alibabacloud Cksync Plan？

由 alibabacloud-skills-team（@sdk-team）开发并维护，当前版本 v0.0.1。

Alibabacloud Cksync Plan