# ck-migrator

**Repository Path**: dbother/ck-migrator

## Basic Information

- **Project Name**: ck-migrator
- **Description**: 用于CK 之间的数据迁移
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-01
- **Last Updated**: 2025-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ClickHouse 数据迁移工具

一个高效可靠的ClickHouse集群间数据迁移工具，支持字段映射、批量处理和迁移速率控制。
采用 remote 函数进行数据查询，程序不会占用太多资源，支持任意 ClickHouse 集群间的数据迁移。

## 功能特性

- ✅ 数据库/表级别的数据迁移
- ✅ 源表和目标表字段映射
- ✅ 批量处理控制(batchSize)
- ✅ 迁移并发控制(Concurrency)
- ✅ 分布式表支持
- ✅ 表筛选模式(include/exclude)
- ✅ 条件过滤(WHERE条件)
- ✅ 自动处理特殊字符防止SQL注入

## 限制
- 建议使用分布式表方式进行迁移
- 需要CK之间网络能连通
- 不支持DDL自动同步
- 不自动创建目标表

## 贡献

欢迎提交Issue和PR。

## 许可证

[MIT](LICENSE)

## 快速开始

### 安装

```bash
go build -o ck-migrator
```

### 配置文件示例

创建 `config.yaml` 文件：

```yaml
source:
  host: "source.clickhouse.host"
  port: 9000
  username: "user"
  password: "password"
  clusterName: "source_cluster"

target:
  host: "target.clickhouse.host"
  port: 9000
  username: "user"
  password: "password"
  clusterName: "target_cluster"

batchSize: 10000
concurrency: 3

# 数据库配置方式1：完整配置
databaseConfig:
  - source: "source_db"
    target: "target_db"
    tables:
      - source: "users"
        target: "user_profiles"
        distributed: true
        columnMapping:
          source: [id, name, email]
          target: [user_id, full_name, email_address]
        condition: "created_at > '2023-01-01'"
      - source: "orders"
        target: "order_details"
        distributed: true
```

### 运行迁移

```
# 基本运行命令
./ck-migrator -c config.yaml

# 生成SQL脚本
./ck-migrator gen sql

# 倒序生成SQL脚本
./ck-migrator gen sql -r

# 执行迁移
./ck-migrator run

# 执行失败的SQL（重新执行）
./ck-migrator run failed
```

## 详细配置说明

### 字段映射

通过 `columnMapping` 配置源表和目标表的字段对应关系：

```yaml
columnMapping:
  source: [src_col1, src_col2]  # 源表字段
  target: [dst_col1, dst_col2]  # 目标表字段
```

注意事项：
1. 源和目标字段数量必须相同
2. 字段顺序一一对应
3. 留空表示迁移所有字段(使用`*`)

### 表筛选模式

支持两种表筛选方式：

1. **完整配置**：明确列出所有要迁移的表
   ```yaml
   databaseConfig:
     - source: "db1"
       target: "db1_new"
       tables:
         - source: "table1"
           target: "table1_new"
   ```

2. **筛选模式**：通过规则批量选择表
   ```yaml
   migrationConfig:
     - dbName: "db2"
       tableAll: true          # 是否迁移所有表
       tableFilterMode: "exclude"  # include|exclude
       tableFilter: ["tmp_"]   # 过滤规则(支持前缀)
   ```

### 性能参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| batchSize | 每批处理的数据量，设置为0表示不进行分片处理，所有数据作为一批处理 | 10000 |
| concurrency | 并发数 | 1 |

## 高级功能

### 倒序生成 SQL 脚本

使用 `-r` 或 `--reverse` 参数生成倒序 SQL 脚本，适用于需要按特定顺序执行迁移的场景：

```bash
./ck-migrator gen sql -r
```

### 分布式表迁移

设置 `distributed: true` 来处理分布式表：

```yaml
tables:
  - source: "dist_table"
    target: "dist_table_new"
    distributed: true
```

工具会自动处理分布式表到本地表的映射关系。

### 条件过滤

通过 `condition` 参数添加WHERE条件：

```yaml
tables:
  - source: "logs"
    condition: "date >= '2023-01-01' AND status = 'active'"
```

### batchSize为0的特殊处理

当 `batchSize` 设置为 0 时，工具会进行特殊处理：
- 不进行数据分片处理，所有数据作为一批处理
- 生成的SQL语句不包含 `farmHash64` 分片函数
- 每个分区只会生成一个SQL语句来处理所有数据

这种模式适用于以下场景：
- 数据量较小，不需要分片处理
- 希望简化SQL语句，避免使用分片函数
- 需要保证数据的完整性和一致性

## 最佳实践

1. **预检查**：
   - 确保源表和目标表结构兼容
   - 验证网络连接和权限

2. **性能调优**：
   - 根据集群性能调整batchSize
   - 合理设置concurrency避免对生产集群造成影响

3. **监控**：
   - 监控ClickHouse系统表(query_log)
   - 关注网络流量

4. **错误处理**：
   - 错误日志会显示具体失败原因
   - 支持断点续传(需手动处理，且可能有重复数据)，最佳方法是删除异常分区数据重新迁移单个分区

### 重新执行失败的SQL

当迁移过程中出现失败的SQL时，这些SQL会被记录在 `failed.sql` 文件中。为了重新执行这些失败的SQL，可以使用以下命令：

```bash
./ck-migrator run failed
```

该命令会读取 `failed.sql` 文件并重新执行其中的SQL语句。

如果需要指定不同的失败SQL文件，可以使用 `-s` 参数：

```bash
./ck-migrator run failed -s /path/to/your/failed.sql
```

注意：在执行 `run failed` 命令之前，如果存在旧的 `failed.sql` 文件，系统会自动将其备份为 `failed.sql.YYYYMMDDHHMMSS` 格式的文件，以防止重要数据丢失。