pgsync Docker镜像文档

镜像概述和主要用途

pgsync Docker镜像是基于pgsync工具构建的容器化解决方案，用于在PostgreSQL数据库之间高效同步数据。该工具旨在简化PostgreSQL实例间的数据复制流程，支持灵活的同步配置，帮助用户轻松维护不同环境或架构中PostgreSQL数据库的数据一致性。

核心功能和特性

• 多模式同步：支持全量同步（完整复制表数据）和增量同步（仅同步变更数据）
• 细粒度控制：可按表、列级别配置同步规则，支持自定义过滤条件
• 事务安全：同步过程中保持事务完整性，避免数据不一致
• 轻量高效：低资源占用，优化的数据传输机制，适合大规模数据同步
• 配置灵活：通过YAML配置文件定义同步规则，支持复杂查询条件和转换逻辑
• 监控与日志：提供详细的同步日志和状态监控，便于问题排查

使用场景和适用范围

适用场景

• 开发/测试环境与生产环境之间的数据同步
• PostgreSQL主从架构中的数据复制
• 跨区域部署的数据库实例间数据同步
• 读写分离架构中的读库数据更新
• 数据库备份与恢复流程中的数据迁移

适用范围

• 所有使用PostgreSQL的开发团队和数据库管理员
• 需要在多个PostgreSQL实例间保持数据一致的场景
• 对同步性能和灵活性有较高要求的业务系统

使用方法和配置说明

基本使用（Docker Run）

bash
docker run --rm \
  -v /path/to/your/config.yml:/app/config.yml \
  -e SOURCE_DB_URL="postgresql://user:password@source-host:5432/source_db" \
  -e TARGET_DB_URL="postgresql://user:password@target-host:5432/target_db" \
  ankane/pgsync sync --config /app/config.yml

Docker Compose配置示例

yaml
version: '3'
services:
  pgsync:
    image: ankane/pgsync
    volumes:
      - ./config.yml:/app/config.yml
    environment:
      - SOURCE_DB_URL=postgresql://user:password@source-db:5432/source_db
      - TARGET_DB_URL=postgresql://user:password@target-db:5432/target_db
    command: sync --config /app/config.yml

配置文件说明

创建config.yml配置文件定义同步规则，示例：

yaml
source:
  url: <%= ENV['SOURCE_DB_URL'] %>
target:
  url: <%= ENV['TARGET_DB_URL'] %>
tables:
  - name: users
    columns:
      - id
      - name
      - email
    where: "created_at > '2023-01-01'"  # 可选过滤条件
  - name: orders
    exclude_columns:
      - internal_notes  # 排除不需要同步的列

环境变量

常用命令

• 执行全量同步：
  docker run ... ankane/pgsync sync --config /app/config.yml --full

• 查看同步状态：
  docker run ... ankane/pgsync status --config /app/config.yml

• 生成默认配置文件：
  docker run --rm -v $(pwd):/app ankane/pgsync init > config.yml

注意事项

• 确保源数据库和目标数据库的网络互通，且用户具有足够权限（如SELECT、INSERT、UPDATE权限）
• 首次同步建议使用--full参数执行全量同步，后续可通过增量同步保持数据一致
• 复杂同步规则建议先在测试环境验证，避免影响生产数据
• 大规模数据同步时，建议调整SYNC_INTERVAL和批处理大小以优化性能