# clickhouse-sync **Repository Path**: djxchi/clickhouse-sync ## Basic Information - **Project Name**: clickhouse-sync - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-02-25 - **Last Updated**: 2025-02-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ClickHouse-MySQL 同步工具 ## 项目简介 ClickHouse-MySQL同步工具是一个用Java开发的数据同步应用，用于实现MySQL数据库到ClickHouse数据库的实时或批量数据同步。本工具支持增量同步和全量同步，适用于需要将MySQL中的事务型数据转移到ClickHouse进行分析处理的场景。 ## 功能特点 - 支持MySQL到ClickHouse的数据实时同步 - 基于MySQL binlog实现增量数据捕获和同步 - 支持全量数据初始化加载 - 提供数据转换和映射功能 - 支持表结构自动创建和更新 - 提供监控和管理界面 - 支持高可用配置 - **新增**：在启动增量同步时，系统会检查上一次的binlog位置。如果存在，则进行增量同步；如果不存在，则进行全量同步。此逻辑确保了数据同步的完整性和连续性。 - **新增**：在同步设置中添加了复选框，允许用户选择在创建新表之前删除已有的表。此功能确保用户在进行表创建时可以选择清除旧数据。 - **新增**：在同步设置中添加了磁盘刷新间隔配置项，用户可以设置磁盘刷新间隔（毫秒），建议值为1000-5000。此配置项有助于优化数据同步的性能。 - **更新**：将删除已有表的复选框移动到同步表输入框的下方，以提高用户界面的可用性和理解性。 ## 系统架构 系统主要包含以下几个核心模块： 1. **数据源读取模块**：负责从MySQL读取数据，包括全量数据读取和基于binlog的增量数据捕获 2. **数据转换模块**：负责数据类型转换和表结构映射 3. **数据写入模块**：负责将转换后的数据写入ClickHouse 4. **调度和监控模块**：负责任务调度、状态监控和异常处理 5. **配置管理模块**：提供Web界面进行配置管理 ## 技术栈 - Java 11+ - Spring Boot - MySQL Connector/J - MySQL Binlog Connector - ClickHouse JDBC Driver - Zookeeper (用于分布式协调) - MyBatis (数据访问) - Apache Kafka (可选，用于消息缓冲) - Vue.js (前端界面) ## 快速开始 ### 环境要求 - JDK 11或更高版本 - Maven 3.6+ - MySQL 5.7+ - ClickHouse 21.8+ ### 安装步骤 1. 克隆代码库 ``` git clone https://github.com/yourusername/clickhouse-sync.git cd clickhouse-sync ``` 2. 配置连接信息 将`config/application-sample.properties`复制为`config/application.properties`，然后修改MySQL和ClickHouse的连接信息： ``` cp config/application-sample.properties config/application.properties vim config/application.properties ``` 主要配置项包括： - MySQL连接信息（host、port、username、password、database） - ClickHouse连接信息（host、port、username、password、database） - 同步表配置（sync.tables） - 同步模式配置（sync.mode） - binlog配置（如果启用增量同步） 3. 编译项目 ``` mvn clean package ``` 4. 启动应用 ``` java -jar target/clickhouse-sync-1.0.0.jar ``` 5. 访问Web管理界面 打开浏览器，访问`http://localhost:8080` ### 使用说明 #### Web管理界面 Web管理界面提供以下功能： - 查看同步状态和配置信息 - 初始化同步环境（创建ClickHouse表结构等） - 执行全量同步 - 启动/停止增量同步 - 查看表结构信息 - 配置MySQL和ClickHouse连接信息及同步参数（通过配置页面） ##### 主页面（index.html） 主页面提供同步状态监控和控制功能： - 显示当前同步状态 - 提供初始化、开始和停止同步的操作按钮 - 显示同步模式和表信息 - 支持全量同步指定表 - 查看表结构信息 ##### 配置页面（config.html） 配置页面用于设置同步工具的各项参数： - MySQL连接配置（主机、端口、用户名、密码、数据库） - ClickHouse连接配置（主机、端口、用户名、密码、数据库） - 同步参数配置（同步模式、同步表、批处理大小等） - 保存和加载配置 #### API接口 系统提供以下REST API接口： - `POST /api/sync/init`：初始化同步环境 - `POST /api/sync/full/{tableName}`：执行指定表的全量同步 - `POST /api/sync/incremental/start`：开始增量同步 - `POST /api/sync/incremental/stop`：停止增量同步 - `GET /api/sync/table/{tableName}`：获取表结构信息 - `GET /api/sync/status`：获取同步状态 - `GET /api/config`：获取当前配置 - `POST /api/config`：更新配置信息 ## 实现原理 ### 全量同步 全量同步通过JDBC直接从MySQL读取表数据，分批次写入ClickHouse。过程如下： 1. 读取MySQL表结构 2. 在ClickHouse中创建对应的表结构 3. 分批次查询MySQL表数据 4. 转换数据类型 5. 批量写入ClickHouse ### 增量同步 增量同步基于MySQL的binlog机制，通过订阅binlog事件来捕获数据变更。过程如下： 1. 连接MySQL的binlog 2. 订阅数据变更事件（INSERT/UPDATE/DELETE） 3. 解析事件数据 4. 转换成ClickHouse支持的格式 5. 写入ClickHouse **注意**：ClickHouse不支持直接的行级更新和删除操作，所以DELETE事件需要特殊处理，一般采用以下策略： - 使用ReplacingMergeTree引擎并添加版本字段 - 使用软删除标记 - 定期重建表 ## 性能优化 - 批量写入：默认使用批量写入提高吞吐量 - 数据压缩：ClickHouse支持多种压缩算法，可根据需要配置 - 分片与分区：对于大表可考虑使用分片和分区策略 - 并行处理：全量同步支持多线程并行处理 ## 常见问题解答 1. **binlog配置问题** 确保MySQL开启了binlog，并且设置了正确的binlog格式（ROW格式）： ``` log_bin = ON binlog_format = ROW ``` 2. **同步性能问题** - 增大批处理大小（sync.batch-size） - 优化MySQL查询（添加适当的索引） - 调整ClickHouse写入设置 3. **类型转换错误** 检查MySQL和ClickHouse的类型映射关系，必要时在代码中自定义转换逻辑。 ## 开发计划 - [x] 项目基础架构搭建 - [x] MySQL数据源读取模块 - [x] ClickHouse写入模块 - [x] 数据转换模块 - [x] 增量同步实现 - [x] Web管理界面 - [ ] 监控和报警功能 - [ ] 高可用配置 - [ ] 支持更多数据类型和特殊字段 - [ ] 性能优化和基准测试 ## 贡献指南 欢迎提交问题和功能请求。如果您想贡献代码，请先fork本仓库，然后提交pull request。 ## 许可证 本项目采用MIT许可证 - 详见LICENSE文件 ## MySQL到ClickHouse同步功能 ### 功能简介 本工具现在支持从MySQL到ClickHouse的全量同步和增量同步。 ### API接口 #### 1. 全量同步 - **请求方式**: `POST` - **接口地址**: `/api/sync/mysql/full/{tableName}` - **参数**: - `tableName`: 要同步的MySQL表名 - **功能**: 执行MySQL到ClickHouse的全量同步。 #### 2. 增量同步 - **请求方式**: `POST` - **接口地址**: `/api/sync/mysql/incremental/start` - **功能**: 开始MySQL到ClickHouse的增量同步。 - **请求方式**: `POST` - **接口地址**: `/api/sync/mysql/incremental/stop` - **功能**: 停止MySQL到ClickHouse的增量同步。 ### 同步状态 - **请求方式**: `GET` - **接口地址**: `/api/sync/mysql/status` - **功能**: 获取当前的同步状态信息。 ## 配置持久化 为了防止在重启后丢失同步配置，工具现在支持将配置持久化到 `application.properties` 文件中。每次更新binlog位置时，配置将自动保存到该文件中。 ## 接口说明 ### 获取当前配置 - **请求方式**: `GET /api/config` - **返回**: - `success`: 请求是否成功 - `config`: 返回的SyncConfig对象，包含MySQL和ClickHouse的配置信息。 ### 示例返回 ```json { "success": true, "config": { "mysql.host": "localhost", "mysql.port": 3306, "mysql.username": "user", "mysql.password": "password", "mysql.database": "dbname", "clickhouse.host": "localhost", "clickhouse.port": 8123, "clickhouse.username": "user", "clickhouse.password": "password", "clickhouse.database": "dbname", "sync.mode": "incremental", "sync.tables": ["table1", "table2"], "sync.batch.size": 100, "sync.binlog.enabled": true, "sync.full.import.enabled": false, "sync.binlog.filename": "binlog.000001", "sync.binlog.position": 12345, "sync.delete.existing.tables": false, "sync.disk.flush.interval": 1000 } } ``` ## 页面结构说明 ### 配置页面 配置页面用于设置MySQL和ClickHouse的连接信息以及同步配置。主要包含以下部分： 1. **MySQL配置**： - 主机地址：MySQL数据库的主机地址。 - 端口：MySQL数据库的端口，默认为3306。 - 用户名：连接MySQL数据库的用户名。 - 密码：连接MySQL数据库的密码。 - 数据库名：要同步的MySQL数据库名称。 2. **ClickHouse配置**： - 主机地址：ClickHouse数据库的主机地址。 - 端口：ClickHouse数据库的端口，默认为8123。 - 用户名：连接ClickHouse数据库的用户名。 - 密码：连接ClickHouse数据库的密码。 - 数据库名：要同步的ClickHouse数据库名称。 3. **同步设置**： - 同步模式：选择全量同步、增量同步或全量+增量同步。 - 同步表：指定要同步的表，多个表以逗号分隔。 - 删除已有表：在创建新表之前删除已有的表。 - 磁盘刷新间隔：设置磁盘刷新间隔（毫秒），建议1000-5000。 - 批处理大小：每批次同步的数据行数，建议1000-5000。 - 启用binlog同步：使用MySQL的binlog机制进行增量同步。 - 启用全量导入：在同步开始时执行全量导入。 4. **Binlog配置**： - Binlog文件名：指定从哪个binlog文件开始同步。 - Binlog位置：指定从binlog文件的哪个位置开始同步。 ## 优化建议 - 确保在主流浏览器中测试页面，以验证其兼容性和响应性。 - 考虑使用HTML5的高级特性，如Canvas、SVG等，以增强用户体验。 - 优化页面加载性能，包括CSS压缩和图片优化。