# db-sync

**Repository Path**: sheyongjun-python/db-sync

## Basic Information

- **Project Name**: db-sync
- **Description**: 不同数据源同步工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-09
- **Last Updated**: 2026-01-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DB-Sync 数据库同步工具

## 📖 简介

DB-Sync 是一个轻量级的 MySQL 数据库同步工具，支持全量同步、增量同步和追加模式。适用于开发、测试、生产环境之间的数据同步场景。

### ✨ 核心特性

- ✅ 支持三种同步模式：全量、增量、追加
- ✅ 批量处理，支持大表同步
- ✅ 模糊匹配表名（支持多个前缀）
- ✅ 自动创建目标表结构
- ✅ 详细的进度日志
- ✅ 事务保护，确保数据一致性
- ✅ 灵活的配置方式（配置文件/命令行参数）
- ✅ 支持从文件读取表名列表

---

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install pymysql
```

### 2. 配置数据库连接

创建配置文件 `my_config.yaml`：

```yaml
# DB-Sync 配置文件

environments:
  # 源数据库配置
  source:
    type: mysql
    host: jump.hcops.cn
    port: 33061
    database: hcyy_ipaas
    username: your_username
    password: your_password
    params:
      timeout: 30

  # 目标数据库配置
  target:
    type: mysql
    host: 10.9.192.101
    port: 3306
    database: hcyy_ipaas
    username: your_username
    password: your_password
    params:
      timeout: 30

# 同步配置
sync_config:
  batch_size: 1000
  timeout: 3600
  backup_before_sync: false
```

### 3. 运行同步

```bash
# 同步单个表
python db_sync.py --config my_config.yaml --source source --target target --tables req_supplier --mode full

# 模糊匹配所有 req 开头的表
python db_sync.py --config my_config.yaml --source source --target target --tables req --fuzzy --mode full

# 使用测试脚本
python test_sync.py --config my_config.yaml --tables req_supplier --mode full
```

---

## 📋 使用方式

### 方式一：主程序（db_sync.py）

#### 基本语法

```bash
python db_sync.py --config <配置文件> --source <源环境> --target <目标环境> --tables <表名> [选项]
```

#### 参数说明

| 参数 | 简写 | 必需 | 说明 | 示例 |
|------|--------|--------|------|--------|
| `--config` | `-c` | 是 | 配置文件路径 | `--config my_config.yaml` |
| `--source` | `-s` | 是 | 源环境名称 | `--source prod` |
| `--target` | `-t` | 是 | 目标环境名称 | `--target staging` |
| `--tables` | | 是 | 表名（逗号分隔）或前缀 | `--tables req_supplier,req_company` |
| `--fuzzy` | | 否 | 模糊匹配模式 | `--fuzzy` |
| `--mode` | `-m` | 否 | 同步模式 | `--mode full` |
| `--batch-size` | `-b` | 否 | 批次大小 | `--batch-size 1000` |
| `--verbose` | `-v` | 否 | 详细日志 | `--verbose` |

#### 同步模式

| 模式 | 说明 | 适用场景 | 性能 |
|------|------|---------|------|
| `full` | 清空目标表后重新插入所有数据 | 首次同步、数据量小 | 慢 |
| `incremental` | 基于时间戳只同步新增和修改的数据 | 大表、频繁更新 | 快 |
| `append` | 在目标表基础上追加数据 | 日志表、追加场景 | 中 |

#### 使用示例

**精准匹配单个表**
```bash
python db_sync.py --config my_config.yaml --source source --target target --tables req_supplier --mode full
```

**精准匹配多个表**
```bash
python db_sync.py --config my_config.yaml --source source --target target --tables req_supplier,req_company,req_customer --mode full
```

**模糊匹配单个前缀**
```bash
python db_sync.py --config my_config.yaml --source source --target target --tables req --fuzzy --mode full
```

**模糊匹配多个前缀**
```bash
python db_sync.py --config my_config.yaml --source source --target target --tables req,api,ecs --fuzzy --mode full
```

**增量同步**
```bash
python db_sync.py --config my_config.yaml --source source --target target --tables req_supplier --mode incremental
```

**追加模式**
```bash
python db_sync.py --config my_config.yaml --source source --target target --tables logs --mode append
```

**自定义批次大小**
```bash
python db_sync.py --config my_config.yaml --source source --target target --tables req_supplier --mode full --batch-size 500
```

---

### 方式二：测试脚本（test_sync.py）

测试脚本提供更灵活的参数配置和详细的测试报告。

#### 基本语法

```bash
python test_sync.py --config <配置文件> --tables <表名> [选项]
```

或使用动态数据库参数：

```bash
python test_sync.py --source-host <主机> --source-port <端口> --source-db <数据库> --source-user <用户> --source-pass <密码> \
                  --target-host <主机> --target-port <端口> --target-db <数据库> --target-user <用户> --target-pass <密码> \
                  --tables <表名> [选项]
```

#### 参数说明

| 参数 | 简写 | 必需 | 说明 | 示例 |
|------|--------|--------|------|--------|
| `--config` | `-c` | 否* | 使用配置文件 | `--config my_config.yaml` |
| `--source-host` | | 是* | 源数据库主机 | `--source-host localhost` |
| `--source-port` | | 否 | 源数据库端口 | `--source-port 3306` |
| `--source-db` | | 是* | 源数据库名 | `--source-db test_db` |
| `--source-user` | | 是* | 源数据库用户名 | `--source-user root` |
| `--source-pass` | | 是* | 源数据库密码 | `--source-pass 123456` |
| `--target-host` | | 是* | 目标数据库主机 | `--target-host localhost` |
| `--target-port` | | 否 | 目标数据库端口 | `--target-port 3306` |
| `--target-db` | | 是* | 目标数据库名 | `--target-db test_db2` |
| `--target-user` | | 是* | 目标数据库用户名 | `--target-user root` |
| `--target-pass` | | 是* | 目标数据库密码 | `--target-pass 123456` |
| `--tables` | `-t` | 是† | 表名或前缀 | `--tables req_supplier` |
| `--tables-file` | `-f` | 是† | 从文件读取表名 | `--tables-file tables.txt` |
| `--fuzzy` | | 否 | 模糊匹配模式 | `--fuzzy` |
| `--mode` | `-m` | 否 | 同步模式 | `--mode full` |
| `--batch-size` | `-b` | 否 | 批次大小 | `--batch-size 1000` |
| `--verbose` | `-v` | 否 | 详细日志 | `--verbose` |

* 如果不使用 `--config`，则必须提供完整的数据库连接参数
† `--tables` 和 `--tables-file` 二选一

#### 表名文件格式

创建 `tables.txt` 文件：

```txt
# 表名列表文件
# 每行一个表名，或逗号分隔
# # 开头的行是注释，会被忽略

req_supplier
req_company
req_customer
req_department

# 这是注释，会被忽略
# req_employee

# 支持一行多个表（逗号分隔）
req_material,req_material_first
```

#### 使用示例

**使用配置文件 + 表名文件**
```bash
python test_sync.py --config my_config.yaml --tables-file tables.txt --mode full
```

**使用配置文件 + 精准匹配**
```bash
python test_sync.py --config my_config.yaml --tables req_supplier,req_company --mode full
```

**使用配置文件 + 单个前缀模糊匹配**
```bash
python test_sync.py --config my_config.yaml --tables req --fuzzy --mode full
```

**使用配置文件 + 多个前缀模糊匹配**
```bash
python test_sync.py --config my_config.yaml --tables req,api,ecs --fuzzy --mode full
```

**使用完整数据库参数**
```bash
python test_sync.py --source-host jump.hcops.cn --source-port 33061 --source-db hcyy_ipaas --source-user c89f5a51-aca9-4612-9cbc-5bcbfa45b13e --source-pass VQGM4OFS4KjnxkEP \
                  --target-host 10.9.192.101 --target-port 3306 --target-db hcyy_ipaas --target-user hcyy --target-pass Hc_Mysql2023 \
                  --tables req_supplier --mode full
```

**使用详细日志**
```bash
python test_sync.py --config my_config.yaml --tables req_supplier --mode full --verbose
```

---

## 🔍 同步模式详解

### 1. Full（全量同步）

**原理**：清空目标表后重新插入所有数据

**适用场景**：
- 首次同步
- 数据量较小的表
- 需要完全替换目标数据

**执行流程**：
```
1. 验证源表和目标表存在
2. 清空目标表（TRUNCATE）
3. 批量读取源表数据
4. 批量插入到目标表
5. 显示进度和统计
```

**日志示例**：
```
表 req_supplier - 全量同步模式开始
已清空表: req_supplier
表 req_supplier 源数据总行数: 11253
表 req_supplier - 批次 1: 同步 1000 行 (进度: 8%, 已同步: 1000/11253)
表 req_supplier - 批次 2: 同步 1000 行 (进度: 17%, 已同步: 2000/11253)
...
表 req_supplier 批量同步完成: 总共同步 11253 行
表 req_supplier 同步完成: 同步 11253 行
```

### 2. Incremental（增量同步）

**原理**：基于时间戳只同步新增和修改的数据

**适用场景**：
- 大表（百万级数据）
- 频繁更新的表
- 定期同步场景

**执行流程**：
```
1. 检查表结构，查找时间戳字段
2. 获取目标表最新时间戳
3. 查询源表中时间戳更新的数据
4. 只插入新增和修改的数据
```

**支持的时间戳字段**：
- `updated_at`（优先级最高）
- `created_at`
- `update_time`
- `create_time`

**日志示例**：
```
表 req_customer - 增量同步模式开始
目标表 req_customer 最新时间戳: 2024-01-01 10:00:00
查询源表中更新的数据: 1500 行
表 req_customer 同步完成: 同步 1500 行
```

**注意事项**：
- 表必须有时间戳字段
- 如果没有时间戳字段，会自动回退到全量同步
- 只能同步新增和修改，不能同步删除的数据

### 3. Append（追加模式）

**原理**：在目标表基础上追加数据

**适用场景**：
- 日志表
- 历史数据追加
- 不清空目标表

**执行流程**：
```
1. 验证源表和目标表存在
2. 批量读取源表数据
3. 批量插入到目标表（不清空）
```

**日志示例**：
```
表 req_supplier - 追加模式开始
表 req_supplier 源数据总行数: 500
表 req_supplier - 批次 1: 同步 500 行 (进度: 100%, 已同步: 500/500)
表 req_supplier 批量同步完成: 总共同步 500 行
```

---

## 📊 日志说明

### 日志级别

| 级别 | 说明 | 使用场景 |
|--------|------|---------|
| INFO | 关键信息 | 正常运行、同步进度 |
| WARNING | 警告信息 | 表为空、回退模式 |
| ERROR | 错误信息 | 同步失败、连接错误 |
| DEBUG | 调试信息 | 详细执行细节 |

### 日志输出

**不使用 --verbose**（INFO级别）：
```
[步骤1] 测试源数据库连接...
✓ 源数据库 连接成功，共有 23 个表
[步骤2] 测试目标数据库连接...
✓ 目标数据库 连接成功，共有 26 个表
[步骤3] 获取要同步的表...
精准匹配模式，共 1 个表:
  - req_supplier
[步骤4] 开始同步...
表 req_supplier - 批次 1: 同步 1000 行
表 req_supplier - 批次 2: 同步 1000 行
...
```

**使用 --verbose**（DEBUG级别）：
```
2026-01-09 10:36:56 - src.sync.sync_engine - INFO - 表 req_supplier - 全量同步模式开始
2026-01-09 10:36:56 - src.connector.mysql_connector - INFO - 已清空表: req_supplier
2026-01-09 10:36:56 - src.sync.sync_engine - INFO - 表 req_supplier 源数据总行数: 11253
2026-01-09 10:36:56 - src.sync.sync_engine - INFO - 表 req_supplier - 批次 1: 同步 1000 行 (进度: 8%, 已同步: 1000/11253)
...
```

### 进度说明

```
表 req_supplier - 批次 1: 同步 1000 行 (进度: 8%, 已同步: 1000/11253)
                                    ↑              ↑              ↑
                                    批次号        百分比      已同步/总数
```

---

## ⚙️ 配置说明

### 配置文件结构

```yaml
environments:
  source:
    type: mysql                    # 数据库类型
    host: localhost                 # 主机地址
    port: 3306                     # 端口
    database: my_database            # 数据库名
    username: root                  # 用户名
    password: 123456                # 密码
    params:
      timeout: 30                   # 连接超时（秒）

  target:
    type: mysql
    host: localhost
    port: 3306
    database: my_database2
    username: root
    password: 123456
    params:
      timeout: 30

sync_config:
  batch_size: 1000                # 批次大小
  timeout: 3600                   # 同步超时（秒）
  backup_before_sync: false       # 同步前是否备份（暂未实现）
```

### 多环境配置

```yaml
environments:
  prod:
    type: mysql
    host: prod.example.com
    port: 3306
    database: production_db
    username: prod_user
    password: prod_pass

  staging:
    type: mysql
    host: staging.example.com
    port: 3306
    database: staging_db
    username: staging_user
    password: staging_pass

  test:
    type: mysql
    host: localhost
    port: 3306
    database: test_db
    username: root
    password: 123456
```

使用方式：
```bash
# 生产 -> 测试
python db_sync.py --config config.yaml --source prod --target test --tables users --mode full

# 测试 -> 生产
python db_sync.py --config config.yaml --source test --target prod --tables users --mode incremental
```

---

## ❓ 常见问题

### 1. 连接失败

**错误信息**：
```
连接数据库失败: 1273 (HY000): Unknown collation: 'utf8mb4_0900_ai_ci'
```

**解决方案**：
- 使用 `pymysql` 驱动（已默认使用）
- 检查 MySQL 版本兼容性
- 移除配置中的 `charset` 参数

### 2. 表不存在

**错误信息**：
```
目标数据库中表不存在: req_supplier
```

**解决方案**：
- 使用 `--fuzzy` 模式时，工具会自动创建不存在的表
- 手动在目标数据库创建表结构

### 3. 表结构不一致

**错误信息**：
```
批量插入数据失败: (1054, "Unknown column 'result' in 'field list'")
```

**解决方案**：
- 检查源表和目标表结构是否一致
- 在目标数据库中删除该表，让工具自动创建
- 手动调整表结构

### 4. 时间戳字段不存在

**错误信息**：
```
表 req_supplier 没有时间戳字段，回退到全量同步
```

**解决方案**：
- 添加时间戳字段（`updated_at`、`created_at` 等）
- 使用 `full` 模式进行全量同步

### 5. 权限不足

**错误信息**：
```
Access denied for user 'xxx'@'xxx' to database 'xxx'
```

**解决方案**：
- 检查数据库用户权限
- 确保有 SELECT、INSERT、CREATE、TRUNCATE 权限

---

## ⚠️ 注意事项

### 1. 数据安全

- ⚠️ **生产环境同步前务必备份数据**
- ⚠️ 建议在低峰期执行同步
- ⚠️ 大表同步时注意数据库性能影响
- ⚠️ 增量同步不会同步删除的数据

### 2. 性能优化

- 📊 **批次大小**：默认 1000，可根据表大小调整
  - 小表：500-1000
  - 大表：1000-5000
  - 超大表：5000-10000

- 🔄 **同步频率**：
  - 频繁更新：使用增量模式
  - 偶尔更新：使用全量模式
  - 日志表：使用追加模式

### 3. 表结构要求

- ✅ 源表和目标表结构必须一致
- ✅ 增量同步需要时间戳字段
- ✅ 主键和索引建议保持一致
- ✅ 字符集和排序规则建议一致

### 4. 网络要求

- 🌐 确保源数据库和目标数据库网络畅通
- ⏱️ 大表同步时注意网络超时设置
- 🔒️ 使用 SSL 连接时需要额外配置

---

## 📁 项目结构

```
db-sync/
├── db_sync.py              # 主程序入口
├── test_sync.py            # 测试脚本（支持动态参数）
├── my_config.yaml          # 配置文件示例
├── tables.txt              # 表名列表文件示例
├── requirements.txt         # Python 依赖
├── README.md              # 本文档
├── src/                   # 源代码
│   ├── config/           # 配置管理
│   │   ├── manager.py
│   │   └── encrypt.py
│   ├── connector/        # 数据库连接
│   │   └── mysql_connector.py
│   ├── sync/             # 同步引擎
│   │   └── sync_engine.py
│   └── utils/            # 工具函数
│       ├── common.py
│       └── error.py
├── config/                # 配置模板
│   └── config_template.yaml
└── tests/                 # 测试
    └── test_config.py
```

---

## 🎯 最佳实践

### 1. 首次同步

```bash
# 使用全量模式同步所有表
python db_sync.py --config my_config.yaml --source prod --target staging --tables req --fuzzy --mode full
```

### 2. 定期增量同步

```bash
# 每天执行一次增量同步
python db_sync.py --config my_config.yaml --source prod --target staging --tables req_supplier,req_company --mode incremental
```

### 3. 大表同步

```bash
# 增大批次大小，减少网络开销
python db_sync.py --config my_config.yaml --source prod --target staging --tables big_table --mode full --batch-size 5000
```

### 4. 多前缀同步

```bash
# 同步多个业务模块的表
python db_sync.py --config my_config.yaml --source prod --target staging --tables req,api,ecs,wms --fuzzy --mode full
```

### 5. 使用表名文件

```bash
# 从文件读取表名，便于管理
python test_sync.py --config my_config.yaml --tables-file tables.txt --mode full
```

---

## 🔧 故障排查

### 查看详细日志

```bash
# 使用 --verbose 参数查看详细日志
python db_sync.py --config my_config.yaml --source prod --target staging --tables req_supplier --mode full --verbose
```

### 测试数据库连接

```bash
# 使用测试脚本的连接测试功能
python test_sync.py --config my_config.yaml --tables req_supplier --mode full
```

### 检查表是否存在

```bash
# 连接数据库后手动检查
mysql -h host -u user -p database -e "SHOW TABLES LIKE 'req%'"
```

### 查看表结构

```bash
# 比较源表和目标表结构
mysql -h source_host -u user -p source_db -e "DESCRIBE table_name"
mysql -h target_host -u user -p target_db -e "DESCRIBE table_name"
```

---

## 📞 技术支持

### 依赖版本

- Python 3.7+
- pymysql 1.0+

### 兼容性

- MySQL 5.7+
- MariaDB 10.3+

### 已知限制

- 不支持跨数据库类型同步（如 MySQL 到 PostgreSQL）
- 不支持表结构自动迁移
- 增量同步不支持删除同步

---

## 📄 版本历史

### v1.0.0 (2024-01-09)

- ✅ MVP 版本发布
- ✅ 支持全量、增量、追加同步
- ✅ 支持批量处理
- ✅ 支持模糊匹配表名
- ✅ 支持多个前缀模糊匹配
- ✅ 支持从文件读取表名
- ✅ 详细的进度日志
- ✅ 自动创建目标表结构
- ✅ 灵活的配置方式

---

## 📝 许可证

MIT License

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

## 📧 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 GitHub Issue
- 发送邮件至项目维护者

---

**祝使用愉快！** 🎉