# pg-cdc

**Repository Path**: seemswork/pg-cdc

## Basic Information

- **Project Name**: pg-cdc
- **Description**: redis-cdc
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-28
- **Last Updated**: 2026-01-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PostgreSQL CDC 到 Redis

[![Go Version](https://img.shields.io/badge/Go-1.24+-blue.svg)](https://golang.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

[English](README.md) | 中文

一个高性能的变更数据捕获 (CDC) 工具，实时将 PostgreSQL 变更流式传输到 Redis，灵感来源于 [Sequin](https://github.com/sequinstream/sequin)。使用 Go 构建，注重效率和可扩展性。

## 🚀 特性

- **实时复制**: 利用 PostgreSQL 逻辑复制实现即时变更捕获
- **多 Redis 支持**: 完全支持所有 Redis 数据结构 (字符串、哈希、列表、集合、有序集合)
- **灵活映射**: 基于模板的键/值生成，支持自定义数据转换
- **高性能**: 使用 goroutines、worker pools 和连接池优化
- **可观测性**: 集成 Prometheus 指标和 Zap 结构化日志
- **可恢复复制**: 通过 Redis 检查点实现容错操作
- **分布式锁**: 基于 Redis 的锁，支持多实例部署
- **配置热重载**: 基于 Viper 的 YAML 配置

## 🏗️ 架构

```
PostgreSQL (WAL) → pglogrepl → CDC 处理器 → Redis
     ↓                    ↓              ↓
逻辑复制              解析事件         模板渲染
```

## 📋 前置要求

- **PostgreSQL 10+** 启用逻辑复制:
  ```sql
  ALTER SYSTEM SET wal_level = logical;
  ALTER SYSTEM SET max_wal_senders = 10;
  ALTER SYSTEM SET max_replication_slots = 10;
  ```
- **Redis 5+** 服务器
- **Go 1.24+** 用于构建

## 🛠️ 安装

1. **克隆仓库**:

   ```bash
   git clone https://github.com/yourusername/pg-cdc.git
   cd pg-cdc
   ```

2. **安装依赖**:

   ```bash
   go mod download
   ```

3. **构建二进制文件**:
   ```bash
   go build ./cmd/pg-cdc
   ```

## ⚙️ 配置

在项目根目录创建 `config.yaml` 文件:

```yaml
postgresql:
  conn_string: "postgres://user:pass@localhost:5432/dbname?replication=database"
  publication: "pgcdc_pub"
  slot: "pgcdc_slot"

redis:
  addr: "localhost:6379"
  password: ""
  db: 0

cdc:
  tables:
    - name: "users"
      redis_type: "hash"
      key_template: "user:{{.id}}"
      fields: ["id", "name", "email"]
    - name: "events"
      redis_type: "list"
      key_template: "events:{{.user_id}}"
      value_template: "{{.event_type}}"
    - name: "scores"
      redis_type: "zset"
      key_template: "leaderboard"
      value_template: "{{.user_id}}"
      score_field: "score"
  checkpoint_key: "cdc_checkpoint"

logging:
  level: "info"

prometheus:
  port: 9090
```

### Redis 数据类型

- **string**: 简单的键值对
- **hash**: 字段值映射
- **list**: 有序集合，支持追加操作
- **set**: 唯一值集合
- **zset**: 带分数的有序集合

## 🚀 使用

1. **启动 PostgreSQL 和 Redis** (使用 Docker):

   ```bash
   docker-compose up -d
   ```

2. **运行 CDC 工具**:

   ```bash
   ./pg-cdc
   ```

3. **监控指标**:
   访问 `http://localhost:9090/metrics` 查看 Prometheus 指标。

4. **执行数据库变更**:
   ```sql
   INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com');
   UPDATE users SET email = 'john.doe@example.com' WHERE id = 1;
   DELETE FROM users WHERE id = 1;
   ```

变更将根据您的配置自动同步到 Redis。

## 📊 监控

### 指标

- `cdc_events_processed_total{table, operation}`: 已处理的变更总数
- `cdc_processing_duration_seconds{table}`: 每表的处理时间

### 日志

可配置级别的结构化 JSON 日志 (debug, info, warn, error)。

## 🧪 测试

```bash
# 运行测试
go test ./...

# 使用 Docker 测试
docker-compose up -d
go run cmd/pg-cdc/main.go
# 执行数据库变更并检查 Redis
```

## 🤝 贡献

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

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- 灵感来源于 [Sequin](https://github.com/sequinstream/sequin)
- 使用 [pgx](https://github.com/jackc/pgx)、[go-redis](https://github.com/redis/go-redis) 等优秀的 Go 库构建

## 📞 支持

如有问题或疑问，请开启 GitHub issue 或联系维护者。