# PgDog 架构解析：PostgreSQL 透明分片与零改动水平扩展 > 深入解析 PgDog 如何通过透明分片路由、SQL 感知路由与事务级连接池实现 PostgreSQL 零改动的水平扩展，涵盖分片策略、路由机制与工程实践要点。 ## 元数据 - 路径: /posts/2026/02/24/pgdog-architecture-transparent-sharding/ - 发布时间: 2026-02-24T01:31:13+08:00 - 分类: [systems](/categories/systems/) - 站点: https://blog.hotdry.top ## 正文 在 PostgreSQL 垂直扩展受限于单机硬件资源的背景下，水平扩展已成为大规模数据处理系统的必选路径。传统方案往往要求应用层感知分片逻辑或在数据库端部署扩展，这一约束显著增加了迁移成本与运维复杂度。PgDog 作为一款 Rust 编写的 PostgreSQL 代理层产品，尝试在应用与数据库之间构建透明的分片抽象，使客户端无需任何修改即可获得水平扩展能力。本文从分片路由、连接池化与架构设计三个维度，解析其核心实现机制与工程实践要点。 ## 代理层的定位与职责 PgDog 定位为 OSI 第七层（应用层）代理，直接解析 PostgreSQL Wire 协议。它同时承担三种角色：连接池管理器、负载均衡器与数据库分片器。这三种能力在同一进程中实现，而非通过多个独立组件组合，这种集成设计有助于减少网络跳数与上下文切换开销。PgDog 不依赖数据库端扩展，部署时仅需在应用与 PostgreSQL 之间增加一层代理进程即可，这正是其「零改动」承诺的技术基础。 代理层启动后会读取两个配置文件：pgdog.toml 定义数据库集群拓扑、分片规则与连接池参数，users.toml 定义认证凭证。配置生效后，PgDog 对外暴露单一端点，客户端将其视为普通 PostgreSQL 服务器连接，而分片细节被完全隐藏在后端拓扑之中。 ## 透明分片路由的实现机制 分片功能的核心在于路由决策的透明性。PgDog 采用声明式配置定义分片策略：在 pgdog.toml 中为同一逻辑数据库声明多个后端节点，每个节点标记独立的 shard 编号。例如，两分片集群可配置为两个数据库条目，分别指向不同的物理实例并标记 shard = 0 与 shard = 1。逻辑上这些后端被视为同一数据库的物理分片，客户端无需感知底层拓扑。 路由算法与 PostgreSQL 原生分区机制保持一致。PgDog 支持 HASH、LIST 与 RANGE 三种分片函数，这些函数与 PostgreSQL 的 PARTITION BY 语法采用相同的底层算法。这意味着在同一分片键条件下，PgDog 与 PostgreSQL 原生分区表对数据分布的判断是一致的。这一设计使得分片集群可以与 postgres_fdw 等原生特性共存，为渐进式迁移提供了技术兼容性。 路由决策分为两种场景。当 SQL 查询包含分片键且可精确定位时，例如 `SELECT * FROM users WHERE user_id = $1`，PgDog 通过解析查询提取分片键值，计算目标分片编号后将请求直接发送至对应后端。这种「直接路由」是分片系统的最优路径，可将查询负载均匀分布至各分片节点。当查询未包含分片键或涉及跨分片操作时，PgDog 将查询广播至所有分片节点，收集结果后在内存中完成聚合、排序与转换，最终以单结果集形式返回客户端。目前支持的跨分片操作包括聚合函数（count、sum、avg、min、max 等）、ORDER BY 与 GROUP BY 条件，以及多行 INSERT 语句的自动拆分。 对于跨分片写事务，PgDog 支持 PostgreSQL 两阶段提交协议。当客户端发送 COMMIT 时，代理层会转换为 PREPARE TRANSACTION 与 COMMIT PREPARED 的完整两阶段流程，确保即使在节点故障场景下也能维持原子性。若客户端在两阶段之间断开连接，PgDog 会根据事务状态自动执行回滚或提交，从而避免悬挂事务导致的数据不一致。 ## 分片键管理与在线扩容 分片键的选择直接影响路由效率。PgDog 在配置中通过 sharded_tables 声明分片表及其分片列，例如 `column = "user_id"` 会将该列作为默认分片键。系统支持两种分片粒度：一是基于表列的分片，常见于用户 ID、订单 ID 等业务主键；二是基于 Schema 的分片，适用于多租户场景，不同租户的数据落入不同的 Schema，PgDog 根据 search_path 或完全限定表名自动路由至对应分片。 在线扩容是分片系统的高频需求。PgDog 实现了基于逻辑复制的在线重分片能力，扩容过程分为五个步骤：首先创建目标分片数量的空集群；然后通过 schema-sync 命令将表结构同步至新节点；接着运行 data-sync 命令利用逻辑复制协议并行迁移历史数据；迁移期间持续同步增量更新；最后通过 MAINTENANCE ON、RELOAD 与 MAINTENANCE OFF 的序列操作完成流量切换。整个过程无需停机，且不依赖 etcd 或 Zookeeper 等外部协调组件，简化了运维复杂度。 ## 连接池与负载均衡 连接池是 PostgreSQL 代理层的标配能力，PgDuck 在此基础上进一步实现了与分片逻辑的深度整合。连接池支持 session 模式与 transaction 模式：session 模式下连接在整个客户端会话期间保持复用；transaction 模式下连接在事务结束后即释放回池，供其他客户端复用。两种模式可并存，系统根据客户端的声明自动选择。 与 PgBouncer 的关键差异在于 PgDog 对 SQL 上下文的处理能力。它能够解析 SET 语句与启动参数，在连接池中为不同客户端正确设置会话状态。例如，当两个客户端使用不同的 search_path 时，PgDog 会在复用后端连接前重置相关会话变量，确保不会发生状态泄露。此外，PgDog 实现了被遗弃事务的自动回滚与连接同步机制，可在应用异常断开时快速回收资源，避免后端连接因事务未提交而被长期占用。 负载均衡方面，PgDog 支持三种策略：轮询（round-robin）、随机（random）与最少活跃连接（least active connections）。在主从拓扑中，系统会自动识别 primary 与 replica 角色，将写操作与 SELECT 发送至不同节点。健康检查机制会实时监控后端状态，故障节点会被自动移除并在恢复后重新加入流量。 ## 工程实践参数与监控建议 部署 PgDog 时，以下参数值得重点关注。default_pool_size 控制每个后端的默认连接池大小，建议根据后端机器规格与查询复杂度设置为 10 至 50 不等；过高可能导致后端连接数成为瓶颈，过低则削弱池化效益。lsn_check_delay 控制复制延迟检查频率，设为 0 时启用实时复制状态监控，适用于需要快速感知主从切换的场景。rewrite.shard_key 与 rewrite.split_inserts 控制分片键更新与多行插入的自动改写行为，可设为 rewrite（自动处理）、ignore（静默丢弃）或 error（拒绝执行）。 监控层面，PgDog 同时暴露 PgBouncer 风格的管理数据库与 OpenMetrics 接口。建议优先使用 OpenMetrics 导出至 Prometheus 或 Datadog，关键指标包括：客户端活跃连接数、后端连接池利用率、查询路由命中率（直接路由 vs 跨分片广播）以及各分片的查询延迟分布。这些指标有助于识别热点分片或路由异常，是容量规划与性能调优的数据基础。 ## 小结 PgDog 通过在代理层集成连接池、负载均衡与分片路由三大能力，为 PostgreSQL 提供了一种无侵入的水平扩展路径。其核心价值在于将分片拓扑从应用层下沉至基础设施层，使现有客户端无需修改即可获得水平扩展能力。分片函数与 PostgreSQL 原生分区机制的对齐设计降低了学习成本，在线重分片能力则解决了扩容这一核心痛点。对于面临单机容量瓶颈、但又希望保持 PostgreSQL 生态与 SQL 完整性的团队，PgDog 提供了一条值得评估的技术路径。 **资料来源**：PgDog 官方 GitHub 仓库（https://github.com/pgdogdev/pgdog）与架构文档（https://docs.pgdog.dev/architecture/）。 ## 同分类近期文章 ### [好奇号火星车遍历可视化引擎：Web 端地形渲染与坐标映射实战](/posts/2026/04/09/curiosity-rover-traverse-visualization/) - 日期: 2026-04-09T02:50:12+08:00 - 分类: [systems](/categories/systems/) - 摘要: 基于好奇号2012年至今的原始Telemetry数据，解析交互式火星地形遍历可视化引擎的坐标转换、地形加载与交互控制技术实现。 ### [卡尔曼滤波器雷达状态估计：预测与更新的数学详解](/posts/2026/04/09/kalman-filter-radar-state-estimation/) - 日期: 2026-04-09T02:25:29+08:00 - 分类: [systems](/categories/systems/) - 摘要: 通过一维雷达跟踪飞机的实例，详细剖析卡尔曼滤波器的状态预测与测量更新数学过程，掌握传感器融合中的最优估计方法。 ### [数字存算一体架构加速NFA评估：1.27 fJ_B_transition 的硬件设计解析](/posts/2026/04/09/digital-cim-architecture-nfa-evaluation/) - 日期: 2026-04-09T02:02:48+08:00 - 分类: [systems](/categories/systems/) - 摘要: 深入解析GLVLSI 2025论文中的数字存算一体架构如何以1.27 fJ/B/transition的超低能耗加速非确定有限状态机评估，并给出工程落地的关键参数与监控要点。 ### [Darwin内核移植Wii硬件：PowerPC架构适配与驱动开发实战](/posts/2026/04/09/darwin-wii-kernel-porting/) - 日期: 2026-04-09T00:50:44+08:00 - 分类: [systems](/categories/systems/) - 摘要: 深入解析将macOS Darwin内核移植到Nintendo Wii的技术挑战，涵盖PowerPC 750CL适配、自定义引导加载器编写及IOKit驱动兼容性实现。 ### [Go-Bt 极简行为树库设计解析：节点组合、状态机与游戏 AI 工程实践](/posts/2026/04/09/go-bt-behavior-trees-minimalist-design/) - 日期: 2026-04-09T00:03:02+08:00 - 分类: [systems](/categories/systems/) - 摘要: 深入解析 go-bt 库的四大核心设计原则，探讨行为树与状态机在游戏 AI 中的工程化选择。