IvorySQL · messere1 · Aug 9, 2026
diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc
@@ -52,6 +52,7 @@
 *** xref:5.9.adoc[pgrouting]
 *** xref:5.10.adoc[system_stats]
 *** xref:5.11.adoc[pgtt]
+*** xref:5.13.adoc[Pgpool-II]
 * 监控运维
 ** xref:3.2.adoc[日常监控]
 ** xref:3.3.adoc[日常维护]

diff --git a/CN/modules/ROOT/pages/5.0.adoc b/CN/modules/ROOT/pages/5.0.adoc
@@ -22,6 +22,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
 | 9 | xref:5.9.adoc[pgrouting] | 3.8.0 | 提供地理空间数据的路由计算功能，支持多种算法和数据格式 | 地理空间分析、路径规划、物流优化
 | 10 | xref:5.10.adoc[system_stats] | 3.2 | 提供用于访问系统级统计信息的函数 | 系统监控 
 | 11 | xref:5.11.adoc[pgtt] | 4.5 | 创建、管理与使用Oracle风格临时表 | 业务开发
+| 12 | xref:5.13.adoc[Pgpool-II] | 4.7.2 | 提供后端连接池、健康检查、流复制状态识别和只读查询负载均衡 | 连接管理、读扩展和高可用架构
 |====
 
 这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。

diff --git a/CN/modules/ROOT/pages/5.13.adoc b/CN/modules/ROOT/pages/5.13.adoc
@@ -0,0 +1,173 @@
+:sectnums:
+:sectnumlevels: 5
+
+= Pgpool-II
+
+== 概述
+
+Pgpool-II 是部署在数据库客户端与 IvorySQL 服务之间的中间件，提供后端长连接池、健康检查、流复制检查、只读查询负载均衡，以及实现自动故障转移所需的基础能力。
+
+本文在 Ubuntu 22.04 x86_64 环境中使用 IvorySQL 5.4（PostgreSQL 18.4）和 Pgpool-II 4.7.2 完成验证。测试拓扑包含一个 IvorySQL 主库和一个流复制备库。
+
+== 已验证的兼容能力
+
+[cols="2,1,3"]
+|===
+|能力 |状态 |验证结果
+
+|使用 IvorySQL 客户端库编译
+|支持
+|使用 IvorySQL 安装目录配置并成功编译 Pgpool-II
+
+|后端连接池
+|支持
+|多个客户端会话能够复用 Pgpool-II 子进程中的后端连接池
+
+|流复制节点识别
+|支持
+|`SHOW POOL_NODES` 正确识别主库和备库
+
+|只读查询负载均衡
+|支持
+|配置相同权重后，两个节点均收到 SELECT 查询
+
+|Oracle 兼容会话
+|支持，存在注意事项
+|会话切换到 `ivorysql.compatible_mode = oracle` 后可通过 Pgpool-II 成功查询
+|===
+
+== 前提条件
+
+* 所有数据库节点均已安装 IvorySQL 5.4。
+* IvorySQL 流复制已经正常工作，备库能够执行只读查询。
+* 编译主机已安装 C 编译器、GNU make、Flex、Bison 和 OpenSSL 开发文件。
+* Pgpool-II 能够访问每个 IvorySQL 节点的 PostgreSQL 兼容端口。
+
+[IMPORTANT]
+Pgpool-II 不负责创建或修复 IvorySQL 流复制。启用 Pgpool-II 前应独立验证复制状态。
+
+== 编译安装 Pgpool-II
+
+[source,shell]
+----
+curl -LO https://www.pgpool.net/source/pgpool-II-4.7.2.tar.gz
+tar -xzf pgpool-II-4.7.2.tar.gz
+cd pgpool-II-4.7.2
+
+./configure \
+  --prefix=/usr/local/pgpool-II-4.7.2 \
+  --with-pgsql=/usr/local/ivorysql/ivorysql-5 \
+  --with-openssl
+make -j"$(nproc)"
+sudo make install
+----
+
+请将 IvorySQL 前缀替换为实际安装目录，该目录下应包含 `bin/pg_config`、`include/postgresql` 和 `lib`。
+
+确认 Pgpool-II 版本：
+
+[source,shell]
+----
+/usr/local/pgpool-II-4.7.2/bin/pgpool --version
+----
+
+== 创建监控角色
+
+在主库创建以下登录角色，并确保角色定义已同步到备库。授予 `pg_monitor` 后，Pgpool-II 无需使用超级用户即可检查流复制状态。
+
+[source,sql]
+----
+CREATE ROLE pgpoolcheck LOGIN PASSWORD 'replace-with-a-strong-password';
+GRANT pg_monitor TO pgpoolcheck;
+----
+
+生产环境应通过 `pool_passwd` 或操作系统密码文件保存密码，不要把明文密码直接写入 `pgpool.conf`。Pgpool-II 支持 SCRAM；请在 `pool_hba.conf` 和各 IvorySQL 节点的 `pg_hba.conf` 中配置相匹配的认证规则。
+
+== 配置 Pgpool-II
+
+复制安装目录中的 `pgpool.conf.sample` 作为起点。以下片段包含双节点验证环境的必要设置：
+
+[source,ini]
+----
+backend_clustering_mode = 'streaming_replication'
+
+listen_addresses = 'localhost'
+port = 9999
+unix_socket_directories = '/tmp'
+
+backend_hostname0 = '10.0.0.11'
+backend_port0 = 5333
+backend_weight0 = 1
+backend_data_directory0 = '/data/ivorysql/primary'
+backend_flag0 = 'DISALLOW_TO_FAILOVER'
+backend_application_name0 = 'ivory_primary'
+
+backend_hostname1 = '10.0.0.12'
+backend_port1 = 5333
+backend_weight1 = 1
+backend_data_directory1 = '/data/ivorysql/standby'
+backend_flag1 = 'DISALLOW_TO_FAILOVER'
+backend_application_name1 = 'ivory_standby'
+
+load_balance_mode = on
+sr_check_period = 10
+sr_check_user = 'pgpoolcheck'
+sr_check_database = 'postgres'
+
+health_check_period = 10
+health_check_user = 'pgpoolcheck'
+health_check_database = 'postgres'
+----
+
+最小配置中使用 `DISALLOW_TO_FAILOVER` 是有意为之，避免不完整示例自动提升或摘除节点。改用 `ALLOW_TO_FAILOVER` 前，必须配置并测试 `failover_command`、备库提升、主库切换后的跟随流程、节点隔离，以及可选的 Watchdog。
+
+验证配置时以前台模式启动 Pgpool-II：
+
+[source,shell]
+----
+/usr/local/pgpool-II-4.7.2/bin/pgpool \
+  -n -f /etc/pgpool-II/pgpool.conf
+----
+
+== 验证集成
+
+连接 Pgpool-II 端口，而不是直接连接后端节点：
+
+[source,shell]
+----
+psql -h pgpool-host -p 9999 -U application_user -d application_db
+----
+
+检查节点发现和查询分布：
+
+[source,sql]
+----
+SHOW POOL_NODES;
+SELECT count(*) FROM application_table;
+SHOW POOL_NODES;
+SHOW POOL_PROCESSES;
+----
+
+IvorySQL 5.4 验证中，Pgpool-II 将两个节点状态均报告为 `up`，角色正确识别为 `primary` 和 `standby`，复制延迟为 0。配置相同权重后，首轮 21 个读查询中，主库执行 9 个，备库执行 12 个。
+
+== Oracle 兼容模式
+
+可以通过池化的 PostgreSQL 兼容连接启用 Oracle 兼容模式：
+
+[source,sql]
+----
+SET ivorysql.compatible_mode = oracle;
+SELECT 'connected through Pgpool-II' AS status FROM dual;
+----
+
+该查询已在 Pgpool-II 后端的 IvorySQL 主备环境中验证通过。
+
+== 运维注意事项
+
+* 本文验证的是 IvorySQL PostgreSQL 兼容端点，不包括通过 `ivorysql.port` 代理 Oracle 客户端协议。
+* Pgpool-II 会解析 SQL 以决定路由位置。应测试应用使用的 Oracle 专用语法，并将必须读取最新数据的语句路由到主库。
+* 异步流复制可能从备库返回旧数据。应根据一致性要求配置延迟阈值或同步复制。
+* 不要在对外服务中使用 `trust` 认证。生产环境应启用 TLS、SCRAM、受限监听地址及最小权限监控账户。
+* 自动故障转移属于独立的高可用设计。启用前必须测试节点提升、隔离、客户端重试和脑裂防护。
+
+生产配置选项请参阅 https://www.pgpool.net/docs/4.7/en/html/[Pgpool-II 4.7 官方文档]。
diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc
@@ -52,6 +52,7 @@
 *** xref:5.9.adoc[pgrouting]
 *** xref:5.10.adoc[system_stats]
 *** xref:5.11.adoc[pgtt]
+*** xref:5.13.adoc[Pgpool-II]
 * Monitor and O&M
 ** xref:3.2.adoc[Monitoring]
 ** xref:3.3.adoc[Maintenance]

diff --git a/EN/modules/ROOT/pages/5.0.adoc b/EN/modules/ROOT/pages/5.0.adoc
@@ -23,6 +23,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
 |*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
 |*10*| xref:5.10.adoc[system_stats] | 3.2 | Provide functions for accessing system-level statistics. | system monitor
 |*11*| xref:5.11.adoc[pgtt] | 4.5 | Create, manage and use Oracle-style Global Temporary Tables. | Business development
+|*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
 |====
 
 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.

diff --git a/EN/modules/ROOT/pages/5.13.adoc b/EN/modules/ROOT/pages/5.13.adoc
@@ -0,0 +1,173 @@
+:sectnums:
+:sectnumlevels: 5
+
+= Pgpool-II
+
+== Overview
+
+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.
+
+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.
+
+== Verified compatibility
+
+[cols="2,1,3"]
+|===
+|Capability |Status |Verification
+
+|Build against IvorySQL client libraries
+|Supported
+|Pgpool-II was configured with the IvorySQL installation prefix and built successfully
+
+|Backend connection pooling
+|Supported
+|Repeated client sessions reused Pgpool-II child-process backend pools
+
+|Streaming-replication discovery
+|Supported
+|`SHOW POOL_NODES` identified the primary and standby correctly
+
+|Read-query load balancing
+|Supported
+|Both nodes received SELECT queries with equal configured weights
+
+|Oracle-compatible sessions
+|Supported with notes
+|A session switched to `ivorysql.compatible_mode = oracle` and queried through Pgpool-II successfully
+|===
+
+== Prerequisites
+
+* IvorySQL 5.4 is installed on every database node.
+* IvorySQL streaming replication is already working and the standby accepts read-only queries.
+* The build host has a C compiler, GNU make, Flex, Bison, and OpenSSL development files.
+* Pgpool-II can reach the PostgreSQL-compatible port of every IvorySQL node.
+
+[IMPORTANT]
+Pgpool-II does not create or repair IvorySQL streaming replication. Verify replication independently before enabling Pgpool-II.
+
+== Build and install Pgpool-II
+
+[source,shell]
+----
+curl -LO https://www.pgpool.net/source/pgpool-II-4.7.2.tar.gz
+tar -xzf pgpool-II-4.7.2.tar.gz
+cd pgpool-II-4.7.2
+
+./configure \
+  --prefix=/usr/local/pgpool-II-4.7.2 \
+  --with-pgsql=/usr/local/ivorysql/ivorysql-5 \
+  --with-openssl
+make -j"$(nproc)"
+sudo make install
+----
+
+Replace the IvorySQL prefix with the directory that contains `bin/pg_config`, `include/postgresql`, and `lib` in your installation.
+
+Confirm that Pgpool-II uses the expected version:
+
+[source,shell]
+----
+/usr/local/pgpool-II-4.7.2/bin/pgpool --version
+----
+
+== Prepare a monitoring role
+
+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.
+
+[source,sql]
+----
+CREATE ROLE pgpoolcheck LOGIN PASSWORD 'replace-with-a-strong-password';
+GRANT pg_monitor TO pgpoolcheck;
+----
+
+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.
+
+== Configure Pgpool-II
+
+Start from the installed `pgpool.conf.sample`. The following excerpt shows the settings essential to a two-node validation deployment:
+
+[source,ini]
+----
+backend_clustering_mode = 'streaming_replication'
+
+listen_addresses = 'localhost'
+port = 9999
+unix_socket_directories = '/tmp'
+
+backend_hostname0 = '10.0.0.11'
+backend_port0 = 5333
+backend_weight0 = 1
+backend_data_directory0 = '/data/ivorysql/primary'
+backend_flag0 = 'DISALLOW_TO_FAILOVER'
+backend_application_name0 = 'ivory_primary'
+
+backend_hostname1 = '10.0.0.12'
+backend_port1 = 5333
+backend_weight1 = 1
+backend_data_directory1 = '/data/ivorysql/standby'
+backend_flag1 = 'DISALLOW_TO_FAILOVER'
+backend_application_name1 = 'ivory_standby'
+
+load_balance_mode = on
+sr_check_period = 10
+sr_check_user = 'pgpoolcheck'
+sr_check_database = 'postgres'
+
+health_check_period = 10
+health_check_user = 'pgpoolcheck'
+health_check_database = 'postgres'
+----
+
+`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.
+
+Start Pgpool-II in the foreground while validating the configuration:
+
+[source,shell]
+----
+/usr/local/pgpool-II-4.7.2/bin/pgpool \
+  -n -f /etc/pgpool-II/pgpool.conf
+----
+
+== Verify the integration
+
+Connect to the Pgpool-II port rather than directly to a backend:
+
+[source,shell]
+----
+psql -h pgpool-host -p 9999 -U application_user -d application_db
+----
+
+Check node discovery and query distribution:
+
+[source,sql]
+----
+SHOW POOL_NODES;
+SELECT count(*) FROM application_table;
+SHOW POOL_NODES;
+SHOW POOL_PROCESSES;
+----
+
+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.
+
+== Oracle-compatible mode
+
+Oracle compatibility can be enabled through the pooled PostgreSQL-compatible connection:
+
+[source,sql]
+----
+SET ivorysql.compatible_mode = oracle;
+SELECT 'connected through Pgpool-II' AS status FROM dual;
+----
+
+The validation succeeded through Pgpool-II and continued to use the replicated backend pair.
+
+== Operational considerations
+
+* This guide validates Pgpool-II on IvorySQL's PostgreSQL-compatible endpoint. It does not validate proxying an Oracle client protocol through `ivorysql.port`.
+* 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.
+* Asynchronous streaming replication can return stale data from a standby. Configure delay thresholds or synchronous replication according to the application's consistency requirements.
+* Do not expose Pgpool-II with `trust` authentication. Use TLS, SCRAM, restricted listen addresses, and least-privilege monitoring accounts in production.
+* Automatic failover is a separate high-availability design. Test promotion, fencing, client retry, and split-brain prevention before enabling it.
+
+For production options, see the https://www.pgpool.net/docs/4.7/en/html/[Pgpool-II 4.7 documentation].