OpenTenBase开发者指南:源码目录导航、pgxc分布式执行引擎剖析与首个PR提交流程
OpenTenBase开发者指南:源码目录导航、pgxc分布式执行引擎剖析与首个PR提交流程
OpenTenBase 是一款企业级分布式 HTAP 开源数据库,由 CoordinateNode、DataNode 与 GTM 节点组成集群,用户数据全部存储在 DataNode 中,CoordinateNode 负责将查询分解为多节点并行执行的片段。本文面向新手开发者,带你快速完成三件事:看懂 OpenTenBase 源码目录结构、剖析 pgxc 分布式执行引擎的核心模块,并走完首个 Pull Request(PR)的完整提交流程。
一、OpenTenBase 源码目录导航:5 分钟看懂仓库结构
初次打开仓库最容易迷路,下面这张表帮你把顶层目录和它的职责一一对应:
| 目录 | 作用 | 新手关注点 |
|---|---|---|
src/ |
数据库内核源码,是仓库的绝对核心 | 先读 src/DEVELOPERS |
src/backend/ |
服务端实现:解析器、优化器、执行器、存储 | 分布式能力集中在 pgxc/ |
src/include/ |
内核头文件 | 按 backend/ 子目录镜像组织 |
src/interfaces/ |
前端接口(如 psql 客户端) | 命令行工具开发参考 |
contrib/ |
官方扩展与运维工具 | contrib/pgxc_ctl/ 是集群管理工具 |
doc/ |
官方文档(SGML 源文件) | doc/src/ |
config/ |
configure 构建脚本 | 一般不需要改动 |
src/test/ |
回归测试与集成测试 | 提交 PR 前必须跑通 |
💡 推荐阅读顺序:README_ZH.md → src/DEVELOPERS → src/backend/ 各模块头文件注释。其中 README_ZH.md 提供了完整的编译步骤(./configure → make -sj → make install),是本地搭建开发环境的第一手资料。
扩展开发同样有成熟的参考路径:contrib/ 下每个扩展都包含 .control 控制文件、--x.x.sql 升级脚本与 .c 源码三件套,例如 contrib/pgvector/Makefile。许多扩展还自带文档,如 Oracle 兼容包 contrib/opentenbase_ora_package_function/ 就附带了完整的函数说明文档:
二、pgxc 分布式执行引擎剖析:一条 SQL 如何跑遍所有节点
OpenTenBase 的分布式能力由 src/backend/pgxc/ 下的 pgxc 执行引擎实现。用户总是连接 CoordinateNode,它会把查询拆分、分发到各 DataNode 并行执行,最后汇总结果。整个引擎按职责拆分为 9 个子模块,每个都小而精:
| 模块 | 核心文件 | 职责 |
|---|---|---|
| nodemgr | nodemgr.c | 节点注册与管理,支撑 CREATE/ALTER/DROP NODE 等 DDL |
| plan | planner.c | 生成 pgxc 风格的分布式执行计划 |
| locator | locator.c | 数据分布定位,决定每个分片落在哪个节点 |
| pool | poolmgr.c、execRemote.c | 与 DataNode 的连接池管理和远程执行 |
| barrier | barrier.c | 节点间屏障同步,保证多节点事务的一致性 |
| shard | shardmap.c | 分片映射,管理表分片与节点的对应关系 |
| copy | copyops.c | 分布式 COPY 数据导入导出 |
| cluster | pause.c | 集群暂停/恢复等全局状态控制 |
| squeue | squeue.c | 服务端队列机制 |
🔍 剖析一条查询的执行链路:
- 计划生成:
planner.c在标准 PostgreSQL 规划器基础上扩展,把查询拆成可下推到 DataNode 的子计划(PGXCPushdownQuery); - 数据定位:
locator.c中的redistrib.c配合 locator,根据分布键判断数据在哪个分片,决定是否需要跨节点重分布; - 远程分发:
pool/execRemote.c通过连接池把子计划发送到对应 DataNode 并行执行; - 结果汇合:
barrier.c通过屏障机制等待所有节点到达同步点,保证分布式事务的原子性,最终由 CoordinateNode 汇总结果返回用户。
如果你想动手验证分布式行为,建议用 contrib/pgxc_ctl/ 工具搭建一个 "1 GTM + 1 Coordinator + 2 DataNode" 的最小集群(搭建步骤见 README_ZH.md),再用 SHOW pgxc_node 等系统视图观察节点状态。
三、提交你的首个 PR:6 步走完整流程
OpenTenBase 社区对贡献非常友好——CONTRIBUTING_ZH.md 明确表示:回答 issue、修复简单 bug 同样有价值。按照贡献指南,完成一个合格 PR 只需 6 步:
第 1 步:Fork 并创建分支
从主分支 fork 出你自己的开发分支,分支名建议用 fix/xxx 或 feature/xxx 前缀,一目了然。
git clone https://gitcode.com/OpenTenBase/OpenTenBase.git
cd OpenTenBase
git checkout -b fix/my-first-bug
第 2 步:定位并阅读相关模块
按第一节的目录导航找到目标文件(改内核就进 src/backend/,改扩展就进 contrib/),先通读目标文件头部的版权与模块说明再动手。
第 3 步:修改代码并同步文档
修改代码后,记得同步更新相关注释与文档,保持行为与描述一致。
第 4 步:为新文件添加许可声明
新建 .c/.h/.sql 文件时,必须加入 License 与 Copyright 声明,可直接参考同目录现有文件的头部格式。
第 5 步:保持代码风格一致 + 充分测试
- 遵循项目既有代码风格(PostgreSQL 系缩进与注释规范);
- 跑通回归测试:
make -C src/test installcheck,改动涉及扩展时在对应contrib/目录下执行其Makefile中的测试目标; - 编译验证:按 README_ZH.md 的
configure→make -sj→make install流程完整构建一次。
第 6 步:提交 PR 并等待审查
将分支推送到远端后,向 dev 分支发起 Pull Request。代码团队会对每个 PR 进行审查与测试,测试通过后接受 PR,但不会立即合并进主分支——耐心等待即可。提交时请在描述中写清楚:改了什么、为什么改、如何验证的,必要时附上截图。
写在最后
掌握 src/ 内核目录导航、理解 pgxc 引擎的四大环节(规划 → 定位 → 分发 → 同步),再按照 6 步流程走通首个 PR,你就已经具备了为 OpenTenBase 持续贡献的能力。建议从 contrib/ 下的扩展文档完善、测试用例补充这类小任务起步,逐步深入到 src/backend/pgxc/ 内核代码,祝你顺利开启分布式数据库内核开发之旅!🚀


