接入方式

通过 DNS、VIP、IP 多种方式接入数据库服务。

Pigsty 提供多种服务接入方式，满足不同场景的需求。

接入架构

┌─────────────────────────────────────────────────────────────────────┐
│                           接入层次                                   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  DNS 域名                                                    │    │
│  │  pg-test → 解析到 VIP 或主库 IP                              │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  VIP 地址（可选）                                            │    │
│  │  10.10.10.3 → 绑定到主库节点                                 │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  HAProxy 服务端口                                            │    │
│  │  :5433 primary  :5434 replica  :5436 default  :5438 offline  │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  数据库实例                                                  │    │
│  │  PostgreSQL :5432  Pgbouncer :6432                          │    │
│  └─────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘

DNS 接入

通过集群域名访问，由 DNSMASQ 提供解析。

域名格式

集群域名：${pg_cluster}
实例域名：${pg_cluster}-${pg_seq}

使用示例

# 集群域名 - 解析到 VIP 或主库
psql postgres://test@pg-test:5433/testdb

# 实例域名 - 解析到特定实例
psql postgres://test@pg-test-1:5433/testdb
psql postgres://test@pg-test-2:5434/testdb

配置

pg_dns_suffix: ""           # DNS 后缀（可选）
pg_dns_target: auto         # 解析目标：auto/vip/primary/ip

VIP 接入

通过 L2 虚拟 IP 访问，由 vip-manager 管理。

工作原理

┌─────────────────────────────────────────────────────────────┐
│                    vip-manager                               │
│                                                              │
│  监视 ETCD 领导者信息                                        │
│         │                                                    │
│         ▼                                                    │
│  当前节点是主库？                                             │
│    是 → 绑定 VIP 到本节点                                    │
│    否 → 释放 VIP                                             │
│                                                              │
│  ┌─────────────┐  故障切换  ┌─────────────┐                 │
│  │  Node 1     │  ────────► │  Node 2     │                 │
│  │  (Primary)  │            │  (Primary)  │                 │
│  │  VIP ✓      │            │  VIP ✓      │                 │
│  └─────────────┘            └─────────────┘                 │
└─────────────────────────────────────────────────────────────┘

使用示例

# 通过 VIP 访问
psql postgres://test@10.10.10.3:5433/testdb

配置

pg_vip_enabled: true              # 启用 VIP
pg_vip_address: 10.10.10.3/24     # VIP 地址
pg_vip_interface: eth0            # 绑定网卡

注意事项

  • 需要 L2 网络可达
  • 所有节点必须在同一 VLAN
  • VIP 地址不能与现有 IP 冲突

端口接入

直接通过 IP + 端口访问。

端口列表

端口 组件 说明
5432 PostgreSQL 数据库直连
6432 Pgbouncer 连接池直连
5433 HAProxy primary 服务
5434 HAProxy replica 服务
5436 HAProxy default 服务
5438 HAProxy offline 服务

使用示例

# PostgreSQL 直连
psql postgres://test@10.10.10.11:5432/testdb

# 通过连接池
psql postgres://test@10.10.10.11:6432/testdb

# 通过 HAProxy 服务
psql postgres://test@10.10.10.11:5433/testdb  # 读写
psql postgres://test@10.10.10.11:5434/testdb  # 只读

智能客户端

使用 libpq 的多主机连接和目标属性。

读写分离

# 多主机 + target_session_attrs
postgres://test@10.10.10.11:6432,10.10.10.12:6432,10.10.10.13:6432/testdb?target_session_attrs=primary

# 只连接主库
?target_session_attrs=primary

# 优先连接从库
?target_session_attrs=prefer-standby

# 任意可用节点
?target_session_attrs=any

优点

  • 客户端自动选择合适节点
  • 无需 VIP 或额外代理
  • 故障自动切换

接入对比

方式 优点 缺点 适用场景
DNS 易于记忆、统一入口 依赖 DNS 服务 通用场景
VIP 透明切换、无需改配置 需要 L2 网络 传统应用
IP:Port 简单直接 硬编码、不灵活 测试开发
智能客户端 原生支持、无额外组件 需要客户端支持 云原生应用

连接字符串示例

生产环境推荐

# 读写业务 - 通过 DNS + primary 服务
postgres://app_user:password@pg-prod:5433/appdb

# 只读业务 - 通过 DNS + replica 服务
postgres://app_user:password@pg-prod:5434/appdb

# 管理操作 - 通过 DNS + default 服务
postgres://dba_user:password@pg-prod:5436/appdb

开发环境

# 直连单机实例
postgres://dev_user:password@10.10.10.10:5432/devdb

ETL 任务

# 使用离线服务，避免影响线上
postgres://etl_user:password@pg-prod:5438/appdb

连接池考量

何时使用连接池

  • 高频短连接场景
  • 连接数超过数据库限制
  • 需要连接复用

何时绕过连接池

  • DDL 操作
  • 大事务、长连接
  • 需要 session 变量
# 通过 5433/5434 经过连接池
postgres://user@host:5433/db

# 通过 5436/5438 绕过连接池
postgres://user@host:5436/db