# sparkflow

**Repository Path**: sparkflow/mysql-binlog-to-clickhouse-sync

## Basic Information

- **Project Name**: sparkflow
- **Description**: 基于 Spring Boot 开发的高性能 MySQL binlog 实时同步工具，支持将 MySQL 数据库的变更实时同步到 ClickHouse 分析型数据库。
- **Primary Language**: Java
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-07-23
- **Last Updated**: 2025-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: clickhouse, mysqlbinlog, 实时同步工具, MySQL

## README

# MySQL Binlog 到 ClickHouse 实时同步工具

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Java](https://img.shields.io/badge/Java-8+-orange.svg)](https://www.oracle.com/java/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7.18-green.svg)](https://spring.io/projects/spring-boot)
[![MySQL](https://img.shields.io/badge/MySQL-5.7+-blue.svg)](https://www.mysql.com/)
[![ClickHouse](https://img.shields.io/badge/ClickHouse-21.0+-yellow.svg)](https://clickhouse.com/)

## 📖 项目简介

基于 Spring Boot 开发的高性能 MySQL binlog 实时同步工具，支持将 MySQL 数据库的变更实时同步到 ClickHouse 分析型数据库。

**核心价值**：
- 🚀 **零侵入性**：无需修改业务代码，基于 MySQL binlog 机制实现数据捕获
- ⚡ **实时性强**：毫秒级数据同步延迟，满足实时分析需求
- 🔄 **高可靠性**：支持断点续传、自动重试，确保数据一致性
- 📈 **高性能**：批量处理、连接池优化，支持大数据量同步

**适用场景**：
- 数据仓库实时ETL
- 业务数据实时分析
- 报表系统数据同步
- 数据湖构建
- 跨系统数据集成

**技术特点**：
采用事件驱动架构，通过监听 MySQL binlog 事件，实时捕获数据变更并同步到 ClickHouse。支持表结构变更(DDL)和数据变更(DML)的完整同步，提供完善的监控和异常处理机制。

## ✨ 核心特性

- **实时同步**: 基于 MySQL binlog 实现毫秒级数据同步
- **智能缓存**: 自动检测和缓存表结构元数据
- **批量处理**: 可配置批处理大小和刷新间隔，优化性能
- **容错机制**: 内置重试逻辑和指数退避算法，保障数据一致性
- **多事件支持**: 支持 INSERT、UPDATE、DELETE 操作同步，以及 CREATE、ALTER、DROP 等 DDL 语句同步
- **断点续传**: 维护 binlog 位点信息，支持故障恢复
- **灵活配置**: 高度可配置的同步策略和连接参数
- **生产就绪**: 完善的日志记录、监控和异常处理机制

## 🚀 快速开始

### 环境要求

- **Java**: JDK 8 或更高版本
- **MySQL**: 5.7+ 且已开启 binlog
- **ClickHouse**: 21.0+ 
- **Maven**: 3.6+ (用于构建)
- **Spring Boot**: 2.7.18

### MySQL 配置

在 MySQL 中启用 binlog：

```sql
-- 启用 binlog
SET GLOBAL log_bin = ON;
SET GLOBAL binlog_format = 'ROW';
SET GLOBAL binlog_row_image = 'FULL';


```

### 安装部署

1. **克隆项目**:
   ```bash
   git clone https://gitee.com/yourusername/mysql-binlog-to-clickhouse-sync.git
   cd mysql-binlog-to-clickhouse-sync
   ```

2. **编译项目**:
   ```bash
   ./mvnw clean package
   ```

3. **配置应用**:
   ```bash
   cp src/main/resources/application.yml.example src/main/resources/application.yml
   # 编辑配置文件，填入数据库连接信息
   ```

4. **启动应用**:
   ```bash
   java -jar target/mysql-binlog-to-clickhouse-sync-0.0.1-SNAPSHOT.jar
   ```

## ⚙️ 配置说明

### 应用配置示例

```yaml
# MySQL 源数据库配置
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/your_database
    username: your_username
    password: your_password

# MySQL Binlog 配置
mysql:
  binlog:
    host: localhost
    port: 3306
    username: sync_user
    password: sync_password
    server-id: 12345
    sync-tables:
      - database1.table1
      - database2.table2

# ClickHouse 目标数据库配置
clickhouse:
  url: jdbc:clickhouse://localhost:8123/default
  user: default
  password: your_password
  connection:
    socket-timeout: 300000      # Socket 超时时间(毫秒)
    connection-timeout: 60000   # 连接超时时间(毫秒)
    max-execution-time: 60      # 最大执行时间(秒)
    max-threads: 4              # 最大线程数
    buffer-size: 65536          # 缓冲区大小
    compress: true              # 是否启用压缩
```

## 📊 监控指标

应用提供完善的监控和指标统计：

- **Binlog 位点**: 跟踪当前 binlog 文件和位置信息
- **同步状态**: 实时显示同步服务运行状态和连接状态
- **事件统计**: 记录 INSERT、UPDATE、DELETE 事件处理数量
- **表同步情况**: 监控各个配置表的同步进度和状态
- **异常记录**: 记录同步过程中的错误和重试情况
- **性能指标**: 监控数据处理速度和系统资源使用情况

监控方式：
- 应用启动日志显示配置信息和连接状态
- 实时日志输出同步事件和处理结果
- 异常日志记录错误详情和堆栈信息

## 🏗️ 系统架构

```
MySQL Binlog → Binlog监听器 → 事件处理器 → 批处理器 → ClickHouse
                     ↓
               位点跟踪器
                     ↓
              元数据缓存
```

### 核心组件

- **BinlogSyncApplication**: 应用程序主入口，负责启动和初始化整个同步服务
- **BinlogEventHandler**: 核心事件处理器，处理 MySQL binlog 的 INSERT、UPDATE、DELETE 事件
- **BinlogEventListener**: Binlog 事件监听器，负责监听和分发 binlog 事件
- **TableMetadataService**: 表结构元数据管理服务，缓存和管理表结构信息
- **MysqlBinlogProperties**: MySQL Binlog 配置属性类，管理连接参数和同步表配置
- **ClickHouseProperties**: ClickHouse 配置属性类，管理连接和同步参数
- **BinlogPositionManager**: Binlog 位点管理器，维护同步位置信息实现断点续传
- **DataSourceConfig**: 数据源配置类，管理 MySQL 和 ClickHouse 数据库连接
- **BinlogConfig**: Binlog 客户端配置类，配置 MySQL binlog 连接客户端
- **TimeUtil**: 时间工具类，处理 MySQL 和 ClickHouse 之间的时间格式转换

## 🔧 开发指南

### 本地开发

```bash
# 克隆仓库
git clone https://gitee.com/yourusername/mysql-binlog-to-clickhouse-sync.git
cd mysql-binlog-to-clickhouse-sync

# 运行测试
./mvnw test

# 构建 JAR 包
./mvnw clean package

# 本地运行
./mvnw spring-boot:run
```

### 项目结构

```
src/
├── main/java/com/sparkflow/mysqlbinlog/clickhousesync/
│   ├── config/          # 配置类
│   ├── listener/        # Binlog 事件监听器
│   ├── service/         # 业务逻辑服务
│   └── util/           # 工具类
└── main/resources/
    ├── application.yml  # 应用配置
   
```

## 🤝 参与贡献

欢迎参与项目贡献！请查看 [贡献指南](CONTRIBUTING.md) 了解详情。

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m '添加某个特性'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 贡献者

感谢所有为项目做出贡献的开发者！

## 📝 开源协议

本项目基于 Apache License 2.0 协议开源，允许自由使用、修改和分发。

### 使用条款

**个人和学习用途**：
- ✅ 免费使用、修改、分发
- ✅ 用于学习、研究、个人项目
- ✅ 开源项目中使用

**商业用途**：
- ⚠️ **商业使用需要授权**：如果您计划将本项目用于商业用途（包括但不限于商业产品、企业内部系统、付费服务等），请联系作者获取商业授权
- 📧 商业授权咨询：965761574@qq.com
- 💼 我们提供灵活的商业授权方案和技术支持服务

**义务和限制**：
- 📄 保留原始版权声明和许可证声明
- 🔄 修改后的代码需要标明修改内容
- ⚖️ 按"现状"提供，不提供任何明示或暗示的担保

### 免责声明

本软件按"现状"提供，作者不对使用本软件造成的任何直接或间接损失承担责任。使用者应自行承担使用风险。

---

查看完整协议内容请参考 [LICENSE](LICENSE) 文件。

## 🆘 技术支持

- **项目文档**: [Wiki](https://gitee.com/yourusername/mysql-binlog-to-clickhouse-sync/wikis)
- **问题反馈**: [Issues](https://gitee.com/yourusername/mysql-binlog-to-clickhouse-sync/issues)
- **讨论交流**: [Gitee 讨论区](https://gitee.com/yourusername/mysql-binlog-to-clickhouse-sync/board)

## 📞 联系方式

- 邮箱: 965761574@qq.com
- QQ群: 1012424863
- 微信群: 暂未开通

## 🙏 致谢

感谢以下开源项目的支持：

- [mysql-binlog-connector-java](https://github.com/shyiko/mysql-binlog-connector-java) - MySQL binlog 连接器
- [ClickHouse JDBC](https://github.com/ClickHouse/clickhouse-jdbc) - ClickHouse JDBC 驱动
- [Spring Boot](https://spring.io/projects/spring-boot) - 应用开发框架

## 🌟 Star 历史

[![Star History Chart](https://api.star-history.com/svg?repos=yourusername/mysql-binlog-to-clickhouse-sync&type=Date)](https://star-history.com/#yourusername/mysql-binlog-to-clickhouse-sync&Date)

---

⭐ **如果这个项目对你有帮助，请给个 Star 支持一下！**

🔥 **欢迎 Fork 和提交 PR，一起完善这个项目！**