# DBSyncer

**Repository Path**: freakchicken/dbsyncer

## Basic Information

- **Project Name**: DBSyncer
- **Description**: 简易上手的数据库同步数据工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用数据库同步工具使用文档


## 1. 简介

本工具是一款基于 Java 开发的通用数据库表同步工具，支持异构数据库之间的数据迁移（如 MySQL -> PostgreSQL, Oracle -> MySQL
等）。工具具备高性能批量写入、事务安全控制以及**可高度定制化的日志系统**，便于生产环境监控与故障排查。

### 1.1 核心特性

- **异构同步**：支持任何提供 JDBC 驱动的数据库。
- **事务安全**：目标端写入采用事务控制，失败自动回滚。
- **批量优化**：支持自定义 Batch Size，提升写入吞吐量。

---

## 2. 环境要求

| 组件    | 最低版本     | 说明                         |
|:------|:---------|:---------------------------|
| JDK   | 1.8      | 建议使用 JDK 11 以获得更好性能        |
| Maven | 3.6.0    | 用于依赖管理和构建                  |
| 数据库驱动 | 取决于具体 DB | 需在 `pom.xml` 中引入对应 JDBC 驱动 |

---

## 3. 安装与构建

### 3.1 克隆代码

```bash
git clone <repository_url>
cd db-sync-tool
```

### 3.2 添加数据库驱动

根据实际使用的数据库，在 `pom.xml` 中添加对应的依赖。例如 MySQL 和 PostgreSQL：

```xml

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.6.0</version>
</dependency>

```

### 3.3 编译打包

```bash
mvn clean package
```

生成物位于 `target/` 目录下。

---

## 4. 配置说明

工具包含两类配置文件，均位于 `src/main/resources` 目录下（打包后位于 classpath 根目录）。

### 4.1 数据源配置 (`db-config.properties`)

用于定义源数据库和目标数据库的连接信息。

```properties
# 源数据库配置 (MySQL)
datasource.mysql_src.driver=com.mysql.cj.jdbc.Driver
datasource.mysql_src.url=jdbc:mysql://localhost:3306/source_db
datasource.mysql_src.username=root
datasource.mysql_src.password=secret_password
datasource.mysql_src.batchSize=1000
# 目标数据库配置 (PostgreSQL)
datasource.pg_target.driver=org.postgresql.Driver
datasource.pg_target.url=jdbc:postgresql://localhost:5432/target_db
datasource.pg_target.username=postgres
datasource.pg_target.password=secret_password
datasource.pg_target.quoteChar="
datasource.pg_target.batchSize=1000
```

**参数说明：**

| 参数键后缀       | 必填  | 说明                                      |
|:------------|:----|:----------------------------------------|
| `driver`    | 是   | JDBC 驱动类名                               |
| `url`       | 是   | 数据库连接 URL                               |
| `username`  | 是   | 数据库用户名                                  |
| `password`  | 是   | 数据库密码                                   |
| `batchSize` | 否   | 批量写入大小，默认 1000                          |
| `quoteChar` | 否   | 表名/字段名引用符，PG 建议填 `"`，MySQL 可留空或 `` ` `` |

> **安全提示**：生产环境中请限制 `db-config.properties` 文件的访问权限（建议 `chmod 600`）。

### 4.2 日志配置 (`logback.xml`)

**本工具的核心优化点**。用于控制日志输出格式、级别、日期格式及输出目标。

#### 4.2.1 自定义日期格式

在 `logback.xml` 中找到 `<property name="LOG_DATE_PATTERN" ... />` 行，修改 `value` 值即可全局更改日期格式。

```xml
<!-- 示例：修改为 ISO8601 格式 -->
<property name="LOG_DATE_PATTERN" value="%d{yyyy-MM-dd'T'HH:mm:ss.SSSZ}"/>

        <!-- 示例：修改为 Unix 时间戳 (毫秒) -->
<property name="LOG_DATE_PATTERN" value="%d{UNIX_MILLIS}"/>

        <!-- 默认推荐：yyyy-MM-dd HH:mm:ss.SSS -->
<property name="LOG_DATE_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS}"/>
```

#### 4.2.2 调整日志级别

开发调试时建议开启 `DEBUG`，生产环境建议设置为 `INFO` 或 `WARN`。

```xml
<!-- 根日志级别 -->
<root level="INFO">
    <appender-ref ref="CONSOLE"/>
    <appender-ref ref="FILE"/>
</root>

        <!-- 特定包级别 -->
<logger name="com.db_sync" level="DEBUG"/>
```


---

## 5. 使用指南

### 5.1 运行方式

确保配置文件已放置在 classpath 中，运行主类 `App`。

```bash
java -cp "target/classes:target/dependency/*" com.db_sync.App
```

### 5.2 代码调用示例

如果您将本工具作为依赖库集成到其他项目中：

```java
public class MySyncJob {
    public static void main(String[] args) {
        // 1. 加载配置
        ConfigLoader.loadAndRegister("db-config.properties");

        // 2. 执行同步 (源 ID, 目标 ID, 表名)
        // 日志会自动记录任务 ID 和上下文
        UniversalDbSync.syncTable("mysql_src", "pg_target", "user_info");
    }
}
```

---


## 7. 常见问题 (FAQ)

### Q1: 日志日期格式修改后不生效？

**A**: 请检查 `logback.xml` 是否被正确加载到 classpath
根目录。修改配置后无需重新编译代码，但通常需要重启应用。确保 `<property name="LOG_DATE_PATTERN" ... />` 没有被其他配置覆盖。

### Q2: 同步速度较慢？

**A**:

1. 检查 `db-config.properties` 中的 `batchSize`，适当增大（如 2000-5000）。
2. 检查日志中的 `平均速度` 统计，若网络延迟高，考虑将工具部署在离数据库更近的服务器。
3. 确保日志级别为 `INFO`，过多的 `DEBUG` 日志会影响 IO 性能。

### Q3: 目标表存在主键冲突怎么办？

**A**: 当前版本采用 `INSERT` 语句。若目标表已有数据且主键冲突，任务会失败回滚。如需覆盖更新，需修改 `executeSync` 方法中的
SQL 逻辑为 `INSERT ON CONFLICT UPDATE` (PG) 或 `REPLACE INTO` (MySQL)。

### Q4: 如何屏蔽第三方库的嘈杂日志？

**A**: 在 `logback.xml` 中添加特定 logger 配置：

```xml

<logger name="org.apache" level="WARN"/>
<logger name="com.zaxxer" level="WARN"/>
```

---


### 8 联系方式

如有问题或建议，请联系开发团队或提交 Issue。