PeerDB-io/peerdb

## PeerDB 在 PeerDB，我们正在构建一种快速、简单且最具成本效益的方式，用于将数据从 Postgres 流式传输到数据仓库、队列和存储引擎。如果您以 Postgres 作为数据栈的核心，并大规模地将数据从 Postgres 移动到上述任何目标，PeerDB 可以为您提供价值。 我们支持不同的流式传输模式——基于日志的（CDC）、基于游标的（时间戳或整数）以及基于 XMIN 的。在性能方面，我们比现有工具快 10 倍。在功能方面，我们支持原生的 Postgres 特性，例如包含 jsonb/数组/地理空间在内的全面数据类型、高效流式传输 TOAST 列、schema 变更等。 ## 开始使用 ``` git clone git@github.com:PeerDB-io/peerdb.git cd peerdb # 运行 docker 容器：postgres 作为 catalog、temporal、PeerDB server、PeerDB flow API + workers、PeerDB UI # 需要安装 docker 和 docker-compose：https://docs.docker.com/engine/install/ bash ./run-peerdb.sh # 或者对于本地开发，镜像将在本地构建。 # 需要 docker、docker-compose 以及用于生成 protobuf 的 buf 编译器 # https://buf.build/docs/installation bash ./generate-protos.sh bash ./dev-peerdb.sh # 连接到 peerdb 并进行查询（使用 psql 版本 >=14.0） psql "port=9900 host=localhost password=peerdb" ``` ### **重要提示：确保 ClickHouse 可访问 MinIO** 如果您的 ClickHouse DB 运行在 Docker 外部（例如，在 VM 或 ClickHouse Cloud 上），它可能无法访问 MinIO，PeerDB 内部使用 MinIO 在加载文件之前暂存文件。请确保 ClickHouse 具有对 MinIO 的网络访问权限。 PeerDB 在 Docker 栈内部的 MinIO 中暂存 PostgreSQL 数据。由于 ClickHouse 在 Docker 外部，它需要一个可解析的 MinIO 主机名。 更新 `docker-compose.yml` 并将 `AWS_ENDPOINT_URL_S3` 设置为 MinIO 的可访问 IP（PeerDB 和 ClickHouse 均可访问）： ``` AWS_ENDPOINT_URL_S3: http://172.31.26.57:9001 # Change this to IP/host which is accessible by both PeerDB and ClickHouse ``` 重新运行 Docker Compose 以应用更改。在 AWS/GCP/Azure 上，还请确保安全组允许对 MinIO 的入站访问。 请按照此 5 分钟的[快速入门指南](https://docs.peerdb.io/quickstart#quickstart)查看 PeerDB 的实际运行情况，即跨存储实时流式传输数据。 ## 为什么选择 PeerDB 当前的数据工具优先考虑广泛的连接器，往往忽略了为 Postgres 用户进行优化。这对于那些在 Postgres 中存储大量数据并频繁传输数据的用户来说可能是个问题。因此，当现有工具无法满足需求时，许多人会求助于构建自定义 pipeline。我们开发这个项目是为了专门为 Postgres 提供一个简单且可靠的解决方案。 ### Postgres 优先的方法 PeerDB 是专为 PostgreSQL 构建的 ETL/ELT 工具。我们实现了多种 Postgres 原生和基础架构优化，以提供快速、可靠且功能丰富的数据进出 PostgreSQL 体验。 **在性能方面** - 我们可以对大表进行并行初始加载，同时确保一致性。同步数百 GB 的数据从几天缩短到几分钟。我们的架构专为实时同步而设计，并实施了多种与逻辑复制相关的优化（例如，调整 Postgres 配置、并行读取 slot）。这使得在大型吞吐量（10k+ tps）下，数据新鲜度仅需几十秒，变更数据捕获（CDC）速度提升了 10 倍。 **在可靠性方面**，我们拥有完善的容错机制——状态管理、自动重试、处理幂等性和一致性等（）。可配置的批处理和并行化可防止内存溢出 (OOMs) 和崩溃。 **从功能丰富性的角度来看**，我们支持高效同步包含大型 (TOAST) 列的表。我们支持多种流式传输模式——基于日志的（CDC）、基于游标的（时间戳或整数）以及基于 XMIN 的。我们提供丰富的数据类型映射，并计划在目标数据存储上尽可能好地支持 Postgres 所支持的每一种（包括自定义类型）类型。 ### 现已在 ClickHouse Cloud 中原生提供（正式可用） PeerDB 现已在 ClickHouse Cloud 中原生提供（正式可用，Generally Available）。在[此处](https://clickhouse.com/cloud/clickpipes/postgres-cdc-connector)了解更多信息。 #### **兼容 Postgres 的 SQL 接口用于执行 ETL** 兼容 Postgres 的 ETL SQL 接口是 PeerDB 独有的，它使您能够使用熟悉的语言进行操作。您可以像操作数据库一样进行 ETL。 您可以使用 Postgres 的生态系统来管理您的 ETL — 1. 使用 pgAdmin、psql 等客户端工具运行 SQL 命令。 2. 使用 Grafana、Tableau 等 BI 工具直观地监控同步和转换。 3. 使用 Flyway 等数据库迁移和版本控制工具来管理您的 ETL。 4. 使用任何语言（例如 Python、Go、Node.js）和调度程序进行开发。 5. 以及更多。 ## 状态 我们扩展了连接器生态系统，以支持除 Postgres 之外的多个源连接器，包括 MySQL 和 MongoDB。您可以在此处查看连接器的状态[这里](https://docs.peerdb.io/sql/commands/supported-connectors) ## 本地端到端测试 您可以在本地运行我们的 CI 用于验证更改的相同端到端测试，从而在开发过程中实现快速迭代。 例如： ``` cd flow go clean -cache go test -v -run TestGenericCH_MySQL ./e2e/ ``` 或者进行本地调试会话。 这些测试需要同时运行 PeerDB 服务、源存储和目标存储。我们提供了一个包含所有必要服务和依赖项的本地环境来运行这些测试。 这是通过 [Tilt](https://tilt.dev/) 编排的 Docker compose 实现的。 要启动环境，您首先需要在本地 `.env` 文件中为测试和测试环境指定共享环境变量。您可以使用提供的 `.env.example` 作为模板：`cp .env.example .env `。 如果项目根目录中存在 `.env` 文件，测试将自动加载它。`.env` 中定义的任何变量都可以由用户提供的环境变量覆盖。 :memo: 在模板中，服务 URL 设置为 `host.docker.internal`，这是 macOS 和 Windows 等 Docker Desktop 设置中默认 Docker 网关的名称。使用默认网关地址允许测试进程和 Docker 内部运行的服务访问主机上的服务。在原生 Docker (Linux) 中，默认情况下无法解析此名称，您可以将其替换为默认网关 IP（例如 `172.18.0.1`），或者在 `/etc/hosts` 文件中添加自定义条目，将 `host.docker.internal` 解析为相应的 IP 地址。例如： ``` echo "172.18.0.1 host.docker.internal" | sudo tee -a /etc/hosts ``` 然后您只需运行： ``` ./tilt.sh ``` 并通过 http://localhost:10352/ 的 Tilt UI 查看服务状态和访问日志。[Dozzle](https://dozzle.dev/) 也包含在内，地址为 http://localhost:8118/，为所有正在运行的 Docker 容器提供实时容器资源利用率指标（CPU、内存）和日志流。 由于 `.env` 是环境配置的唯一事实来源，测试会自动从项目根目录中提取它。例如： ``` go clean -cache; go test -v -run TestGenericCH_MySQL ./e2e/ # Some MySQL generic tests ``` ### 从 Tilt 运行测试 Tilt 设置包含在 `e2e` 标签下预配置的测试启动器资源。这些资源不会自动启动；相反，您可以根据需要从 http://localhost:10352/ 的 Tilt UI 中触发它们。 可用的测试启动器： - **e2e_postgres** -- Postgres 到 ClickHouse 的通用测试 (`TestGenericCH_PG`) - **e2e_mysql-gtid** -- MySQL GTID 到 ClickHouse 的通用测试 (`TestGenericCH_MySQL`) - **e2e_mysql-pos** -- MySQL File-Pos 到 ClickHouse 的通用测试 (`TestGenericCH_MySQL`) - **e2e_mariadb** -- MariaDB 到 ClickHouse 的通用测试 (`TestGenericCH_MySQL`) - **e2e_mongodb** -- MongoDB 到 ClickHouse 的测试套件 (`TestMongoClickhouseSuite`) 每个启动器自动依赖于所需的服务和配置步骤，因此 Tilt 将在执行测试之前确保所有先决条件都在运行。要触发测试，请在 Tilt UI 中单击该资源，然后按触发（播放）按钮。 ### 手动初始化 DataStore DataStore 资源（ClickHouse、MongoDB、MySQL 变体、PostgreSQL）使用**手动初始化**（`auto_init=False`）以节省资源。这允许您根据需要有选择地仅启动测试场景所需的数据库。  要启动 datastore： 1. 导航至 http://localhost:10352/ 的 Tilt UI 2. 找到所需的 DataStore 资源 3. 单击该资源，然后按播放/触发按钮 每个 datastore 的配置步骤将在 datastore 运行后自动执行。 ### 测试多个 MySQL 变体 Tilt 现在支持针对不同的 MySQL 复制模式和 MariaDB 同时运行测试，无需修改文件。每个 MySQL 变体都有自己专用的端口和测试启动器： - **mysql-gtid**（端口 3306）：带 GTID 复制的 MySQL 9.5 - **mysql-pos**（端口 3307）：带 file-position 复制的 MySQL 5.7（使用 `biarms/mysql` 镜像兼容 ARM） - **mariadb**（端口 3308）：带二进制日志复制的 MariaDB 这允许在单个开发会话中跨不同的 MySQL 配置进行全面测试。 ### 命名卷和清理 所有辅助服务现在都使用 Docker Compose 命名卷进行数据持久化。这可以实现： - 环境拆除后的数据分析 - 通过保留数据库状态实现更快的重启 - 通过 Tilt UI 进行轻松清理 要清理未使用的卷，请使用 Tilt UI 导航栏中的**“Wipe ancillary volumes”**按钮：  此按钮删除 `ancillary-docker-compose.yml` 中定义的当前未在使用的所有命名卷。例如，如果禁用了 MongoDB，单击此按钮将删除其数据卷。  ### 环境服务版本 数据存储版本从 `.github/workflows/flow.yml` 中提取，选择测试矩阵的最后一行，但 MySQL 版本默认为 `9.5`。 这种自动提取依赖于 `yq` CLI；请安装基于 Go 的 [`mikefarah/yq`](https://github.com/mikefarah/yq) 版本 4 或更高版本，以便本地环境生成正常工作。 您可以在本地 `.env` 文件中指定不同的版本来覆盖它们，如下所示： ``` MYSQL_VERSION=8.0 MONGODB_VERSION=4.4 CLICKHOUSE_VERSION=21.8 ``` ## 支持 我们的文档可以在[这里](https://docs.peerdb.io/introduction)找到。如果您有任何问题，欢迎访问我们的 [Slack](https://slack.peerdb.io/)！ ## 许可证 PeerDB 根据 GNU Affero General Public License v3.0 (AGPLv3) 获得许可。请查看 LICENSE 文件以获取更多信息。如果您有任何许可问题，请发送电子邮件至 ****

标签：CDC, ClickHouse, ETL, EVTX分析, JavaCC, PostgreSQL, Python工具, 数据仓库, 数据同步, 数据集成, 日志审计, 请求拦截