Skip to content

Commit b3a5953

Browse files
messere1messere1
committed
docs: add Pgpool-II integration guide
Assisted-by: OpenAI:gpt-5
1 parent daefd13 commit b3a5953

6 files changed

Lines changed: 350 additions & 0 deletions

File tree

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
*** xref:5.9.adoc[pgrouting]
5353
*** xref:5.10.adoc[system_stats]
5454
*** xref:5.11.adoc[pgtt]
55+
*** xref:5.13.adoc[Pgpool-II]
5556
* 监控运维
5657
** xref:3.2.adoc[日常监控]
5758
** xref:3.3.adoc[日常维护]

‎CN/modules/ROOT/pages/5.0.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
2222
| 9 | xref:5.9.adoc[pgrouting] | 3.8.0 | 提供地理空间数据的路由计算功能，支持多种算法和数据格式 | 地理空间分析、路径规划、物流优化
2323
| 10 | xref:5.10.adoc[system_stats] | 3.2 | 提供用于访问系统级统计信息的函数 | 系统监控
2424
| 11 | xref:5.11.adoc[pgtt] | 4.5 | 创建、管理与使用Oracle风格临时表 | 业务开发
25+
| 12 | xref:5.13.adoc[Pgpool-II] | 4.7.2 | 提供后端连接池、健康检查、流复制状态识别和只读查询负载均衡 | 连接管理、读扩展和高可用架构
2526
|====
2627

2728
这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。

‎CN/modules/ROOT/pages/5.13.adoc‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= Pgpool-II
5+
6+
== 概述
7+
8+
Pgpool-II 是部署在数据库客户端与 IvorySQL 服务之间的中间件，提供后端长连接池、健康检查、流复制检查、只读查询负载均衡，以及实现自动故障转移所需的基础能力。
9+
10+
本文在 Ubuntu 22.04 x86_64 环境中使用 IvorySQL 5.4（PostgreSQL 18.4）和 Pgpool-II 4.7.2 完成验证。测试拓扑包含一个 IvorySQL 主库和一个流复制备库。
11+
12+
== 已验证的兼容能力
13+
14+
[cols="2,1,3"]
15+
|===
16+
|能力 |状态 |验证结果
17+
18+
|使用 IvorySQL 客户端库编译
19+
|支持
20+
|使用 IvorySQL 安装目录配置并成功编译 Pgpool-II
21+
22+
|后端连接池
23+
|支持
24+
|多个客户端会话能够复用 Pgpool-II 子进程中的后端连接池
25+
26+
|流复制节点识别
27+
|支持
28+
|`SHOW POOL_NODES` 正确识别主库和备库
29+
30+
|只读查询负载均衡
31+
|支持
32+
|配置相同权重后，两个节点均收到 SELECT 查询
33+
34+
|Oracle 兼容会话
35+
|支持，存在注意事项
36+
|会话切换到 `ivorysql.compatible_mode = oracle` 后可通过 Pgpool-II 成功查询
37+
|===
38+
39+
== 前提条件
40+
41+
* 所有数据库节点均已安装 IvorySQL 5.4。
42+
* IvorySQL 流复制已经正常工作，备库能够执行只读查询。
43+
* 编译主机已安装 C 编译器、GNU make、Flex、Bison 和 OpenSSL 开发文件。
44+
* Pgpool-II 能够访问每个 IvorySQL 节点的 PostgreSQL 兼容端口。
45+
46+
[IMPORTANT]
47+
Pgpool-II 不负责创建或修复 IvorySQL 流复制。启用 Pgpool-II 前应独立验证复制状态。
48+
49+
== 编译安装 Pgpool-II
50+
51+
[source,shell]
52+
----
53+
curl -LO https://www.pgpool.net/source/pgpool-II-4.7.2.tar.gz
54+
tar -xzf pgpool-II-4.7.2.tar.gz
55+
cd pgpool-II-4.7.2
56+
57+
./configure \
58+
--prefix=/usr/local/pgpool-II-4.7.2 \
59+
--with-pgsql=/usr/local/ivorysql/ivorysql-5 \
60+
--with-openssl
61+
make -j"$(nproc)"
62+
sudo make install
63+
----
64+
65+
请将 IvorySQL 前缀替换为实际安装目录，该目录下应包含 `bin/pg_config`、`include/postgresql` 和 `lib`。
66+
67+
确认 Pgpool-II 版本：
68+
69+
[source,shell]
70+
----
71+
/usr/local/pgpool-II-4.7.2/bin/pgpool --version
72+
----
73+
74+
== 创建监控角色
75+
76+
在主库创建以下登录角色，并确保角色定义已同步到备库。授予 `pg_monitor` 后，Pgpool-II 无需使用超级用户即可检查流复制状态。
77+
78+
[source,sql]
79+
----
80+
CREATE ROLE pgpoolcheck LOGIN PASSWORD 'replace-with-a-strong-password';
81+
GRANT pg_monitor TO pgpoolcheck;
82+
----
83+
84+
生产环境应通过 `pool_passwd` 或操作系统密码文件保存密码，不要把明文密码直接写入 `pgpool.conf`。Pgpool-II 支持 SCRAM；请在 `pool_hba.conf` 和各 IvorySQL 节点的 `pg_hba.conf` 中配置相匹配的认证规则。
85+
86+
== 配置 Pgpool-II
87+
88+
复制安装目录中的 `pgpool.conf.sample` 作为起点。以下片段包含双节点验证环境的必要设置：
89+
90+
[source,ini]
91+
----
92+
backend_clustering_mode = 'streaming_replication'
93+
94+
listen_addresses = 'localhost'
95+
port = 9999
96+
unix_socket_directories = '/tmp'
97+
98+
backend_hostname0 = '10.0.0.11'
99+
backend_port0 = 5333
100+
backend_weight0 = 1
101+
backend_data_directory0 = '/data/ivorysql/primary'
102+
backend_flag0 = 'DISALLOW_TO_FAILOVER'
103+
backend_application_name0 = 'ivory_primary'
104+
105+
backend_hostname1 = '10.0.0.12'
106+
backend_port1 = 5333
107+
backend_weight1 = 1
108+
backend_data_directory1 = '/data/ivorysql/standby'
109+
backend_flag1 = 'DISALLOW_TO_FAILOVER'
110+
backend_application_name1 = 'ivory_standby'
111+
112+
load_balance_mode = on
113+
sr_check_period = 10
114+
sr_check_user = 'pgpoolcheck'
115+
sr_check_database = 'postgres'
116+
117+
health_check_period = 10
118+
health_check_user = 'pgpoolcheck'
119+
health_check_database = 'postgres'
120+
----
121+
122+
最小配置中使用 `DISALLOW_TO_FAILOVER` 是有意为之，避免不完整示例自动提升或摘除节点。改用 `ALLOW_TO_FAILOVER` 前，必须配置并测试 `failover_command`、备库提升、主库切换后的跟随流程、节点隔离，以及可选的 Watchdog。
123+
124+
验证配置时以前台模式启动 Pgpool-II：
125+
126+
[source,shell]
127+
----
128+
/usr/local/pgpool-II-4.7.2/bin/pgpool \
129+
-n -f /etc/pgpool-II/pgpool.conf
130+
----
131+
132+
== 验证集成
133+
134+
连接 Pgpool-II 端口，而不是直接连接后端节点：
135+
136+
[source,shell]
137+
----
138+
psql -h pgpool-host -p 9999 -U application_user -d application_db
139+
----
140+
141+
检查节点发现和查询分布：
142+
143+
[source,sql]
144+
----
145+
SHOW POOL_NODES;
146+
SELECT count(*) FROM application_table;
147+
SHOW POOL_NODES;
148+
SHOW POOL_PROCESSES;
149+
----
150+
151+
IvorySQL 5.4 验证中，Pgpool-II 将两个节点状态均报告为 `up`，角色正确识别为 `primary` 和 `standby`，复制延迟为 0。配置相同权重后，首轮 21 个读查询中，主库执行 9 个，备库执行 12 个。
152+
153+
== Oracle 兼容模式
154+
155+
可以通过池化的 PostgreSQL 兼容连接启用 Oracle 兼容模式：
156+
157+
[source,sql]
158+
----
159+
SET ivorysql.compatible_mode = oracle;
160+
SELECT 'connected through Pgpool-II' AS status FROM dual;
161+
----
162+
163+
该查询已在 Pgpool-II 后端的 IvorySQL 主备环境中验证通过。
164+
165+
== 运维注意事项
166+
167+
* 本文验证的是 IvorySQL PostgreSQL 兼容端点，不包括通过 `ivorysql.port` 代理 Oracle 客户端协议。
168+
* Pgpool-II 会解析 SQL 以决定路由位置。应测试应用使用的 Oracle 专用语法，并将必须读取最新数据的语句路由到主库。
169+
* 异步流复制可能从备库返回旧数据。应根据一致性要求配置延迟阈值或同步复制。
170+
* 不要在对外服务中使用 `trust` 认证。生产环境应启用 TLS、SCRAM、受限监听地址及最小权限监控账户。
171+
* 自动故障转移属于独立的高可用设计。启用前必须测试节点提升、隔离、客户端重试和脑裂防护。
172+
173+
生产配置选项请参阅 https://www.pgpool.net/docs/4.7/en/html/[Pgpool-II 4.7 官方文档]。

‎EN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
*** xref:5.9.adoc[pgrouting]
5353
*** xref:5.10.adoc[system_stats]
5454
*** xref:5.11.adoc[pgtt]
55+
*** xref:5.13.adoc[Pgpool-II]
5556
* Monitor and O&M
5657
** xref:3.2.adoc[Monitoring]
5758
** xref:3.3.adoc[Maintenance]

‎EN/modules/ROOT/pages/5.0.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
2323
|*9*| xref:5.9.adoc[pgrouting] | 3.8.0 | Provides routing computation for geospatial data, supporting multiple algorithms and data formats | Geospatial analysis, route planning, logistics optimization
2424
|*10*| xref:5.10.adoc[system_stats] | 3.2 | Provide functions for accessing system-level statistics. | system monitor
2525
|*11*| xref:5.11.adoc[pgtt] | 4.5 | Create, manage and use Oracle-style Global Temporary Tables. | Business development
26+
|*12*| xref:5.13.adoc[Pgpool-II] | 4.7.2 | Provides backend connection pooling, health checks, streaming-replication awareness, and read-query load balancing | Connection management, read scaling, and high-availability architectures
2627
|====
2728

2829
These plugins have all been tested and adapted by the IvorySQL team to ensure stable operation in the IvorySQL environment. Users can select appropriate plugins based on business needs to further enhance the capabilities and flexibility of the database system.

‎EN/modules/ROOT/pages/5.13.adoc‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= Pgpool-II
5+
6+
== Overview
7+
8+
Pgpool-II is middleware placed between database clients and IvorySQL servers. It provides persistent backend connection pools, health and streaming-replication checks, read-query load balancing, and building blocks for automated failover.
9+
10+
This guide was verified with IvorySQL 5.4 (PostgreSQL 18.4) and Pgpool-II 4.7.2 on Ubuntu 22.04 x86_64. The validation used one IvorySQL primary and one streaming-replication standby.
11+
12+
== Verified compatibility
13+
14+
[cols="2,1,3"]
15+
|===
16+
|Capability |Status |Verification
17+
18+
|Build against IvorySQL client libraries
19+
|Supported
20+
|Pgpool-II was configured with the IvorySQL installation prefix and built successfully
21+
22+
|Backend connection pooling
23+
|Supported
24+
|Repeated client sessions reused Pgpool-II child-process backend pools
25+
26+
|Streaming-replication discovery
27+
|Supported
28+
|`SHOW POOL_NODES` identified the primary and standby correctly
29+
30+
|Read-query load balancing
31+
|Supported
32+
|Both nodes received SELECT queries with equal configured weights
33+
34+
|Oracle-compatible sessions
35+
|Supported with notes
36+
|A session switched to `ivorysql.compatible_mode = oracle` and queried through Pgpool-II successfully
37+
|===
38+
39+
== Prerequisites
40+
41+
* IvorySQL 5.4 is installed on every database node.
42+
* IvorySQL streaming replication is already working and the standby accepts read-only queries.
43+
* The build host has a C compiler, GNU make, Flex, Bison, and OpenSSL development files.
44+
* Pgpool-II can reach the PostgreSQL-compatible port of every IvorySQL node.
45+
46+
[IMPORTANT]
47+
Pgpool-II does not create or repair IvorySQL streaming replication. Verify replication independently before enabling Pgpool-II.
48+
49+
== Build and install Pgpool-II
50+
51+
[source,shell]
52+
----
53+
curl -LO https://www.pgpool.net/source/pgpool-II-4.7.2.tar.gz
54+
tar -xzf pgpool-II-4.7.2.tar.gz
55+
cd pgpool-II-4.7.2
56+
57+
./configure \
58+
--prefix=/usr/local/pgpool-II-4.7.2 \
59+
--with-pgsql=/usr/local/ivorysql/ivorysql-5 \
60+
--with-openssl
61+
make -j"$(nproc)"
62+
sudo make install
63+
----
64+
65+
Replace the IvorySQL prefix with the directory that contains `bin/pg_config`, `include/postgresql`, and `lib` in your installation.
66+
67+
Confirm that Pgpool-II uses the expected version:
68+
69+
[source,shell]
70+
----
71+
/usr/local/pgpool-II-4.7.2/bin/pgpool --version
72+
----
73+
74+
== Prepare a monitoring role
75+
76+
Create the same login on the primary and make sure its definition reaches the standby. Membership in `pg_monitor` lets Pgpool-II inspect streaming-replication state without using a superuser account.
77+
78+
[source,sql]
79+
----
80+
CREATE ROLE pgpoolcheck LOGIN PASSWORD 'replace-with-a-strong-password';
81+
GRANT pg_monitor TO pgpoolcheck;
82+
----
83+
84+
Use `pool_passwd` or an operating-system password file instead of putting a production password directly in `pgpool.conf`. Pgpool-II supports SCRAM authentication; configure matching rules in `pool_hba.conf` and the IvorySQL `pg_hba.conf` files.
85+
86+
== Configure Pgpool-II
87+
88+
Start from the installed `pgpool.conf.sample`. The following excerpt shows the settings essential to a two-node validation deployment:
89+
90+
[source,ini]
91+
----
92+
backend_clustering_mode = 'streaming_replication'
93+
94+
listen_addresses = 'localhost'
95+
port = 9999
96+
unix_socket_directories = '/tmp'
97+
98+
backend_hostname0 = '10.0.0.11'
99+
backend_port0 = 5333
100+
backend_weight0 = 1
101+
backend_data_directory0 = '/data/ivorysql/primary'
102+
backend_flag0 = 'DISALLOW_TO_FAILOVER'
103+
backend_application_name0 = 'ivory_primary'
104+
105+
backend_hostname1 = '10.0.0.12'
106+
backend_port1 = 5333
107+
backend_weight1 = 1
108+
backend_data_directory1 = '/data/ivorysql/standby'
109+
backend_flag1 = 'DISALLOW_TO_FAILOVER'
110+
backend_application_name1 = 'ivory_standby'
111+
112+
load_balance_mode = on
113+
sr_check_period = 10
114+
sr_check_user = 'pgpoolcheck'
115+
sr_check_database = 'postgres'
116+
117+
health_check_period = 10
118+
health_check_user = 'pgpoolcheck'
119+
health_check_database = 'postgres'
120+
----
121+
122+
`DISALLOW_TO_FAILOVER` is intentional in this minimal configuration: it prevents an incomplete example from promoting or detaching nodes automatically. Before using `ALLOW_TO_FAILOVER`, configure and test `failover_command`, standby promotion, follow-primary handling, fencing, and optionally Watchdog.
123+
124+
Start Pgpool-II in the foreground while validating the configuration:
125+
126+
[source,shell]
127+
----
128+
/usr/local/pgpool-II-4.7.2/bin/pgpool \
129+
-n -f /etc/pgpool-II/pgpool.conf
130+
----
131+
132+
== Verify the integration
133+
134+
Connect to the Pgpool-II port rather than directly to a backend:
135+
136+
[source,shell]
137+
----
138+
psql -h pgpool-host -p 9999 -U application_user -d application_db
139+
----
140+
141+
Check node discovery and query distribution:
142+
143+
[source,sql]
144+
----
145+
SHOW POOL_NODES;
146+
SELECT count(*) FROM application_table;
147+
SHOW POOL_NODES;
148+
SHOW POOL_PROCESSES;
149+
----
150+
151+
In the IvorySQL 5.4 validation, Pgpool-II reported both nodes as `up`, assigned roles `primary` and `standby`, and showed a replication delay of zero. With equal weights, 21 initial read queries were distributed 9 to the primary and 12 to the standby.
152+
153+
== Oracle-compatible mode
154+
155+
Oracle compatibility can be enabled through the pooled PostgreSQL-compatible connection:
156+
157+
[source,sql]
158+
----
159+
SET ivorysql.compatible_mode = oracle;
160+
SELECT 'connected through Pgpool-II' AS status FROM dual;
161+
----
162+
163+
The validation succeeded through Pgpool-II and continued to use the replicated backend pair.
164+
165+
== Operational considerations
166+
167+
* This guide validates Pgpool-II on IvorySQL's PostgreSQL-compatible endpoint. It does not validate proxying an Oracle client protocol through `ivorysql.port`.
168+
* Pgpool-II parses SQL to decide where to route it. Test application-specific Oracle syntax and route statements that must see the newest data to the primary.
169+
* Asynchronous streaming replication can return stale data from a standby. Configure delay thresholds or synchronous replication according to the application's consistency requirements.
170+
* Do not expose Pgpool-II with `trust` authentication. Use TLS, SCRAM, restricted listen addresses, and least-privilege monitoring accounts in production.
171+
* Automatic failover is a separate high-availability design. Test promotion, fencing, client retry, and split-brain prevention before enabling it.
172+
173+
For production options, see the https://www.pgpool.net/docs/4.7/en/html/[Pgpool-II 4.7 documentation].

0 commit comments

Comments
 (0)