From b3a5953910d90ca0659fdbfbf67a3b285c19e3de Mon Sep 17 00:00:00 2001
From: messere1 <189848840+messere1@users.noreply.github.com>
Date: Sun, 9 Aug 2026 20:30:46 +0800
Subject: [PATCH 1/2] docs: add Pgpool-II integration guide

Assisted-by: OpenAI:gpt-5
---
 CN/modules/ROOT/nav.adoc        |   1 +
 CN/modules/ROOT/pages/5.0.adoc  |   1 +
 CN/modules/ROOT/pages/5.13.adoc | 173 ++++++++++++++++++++++++++++++++
 EN/modules/ROOT/nav.adoc        |   1 +
 EN/modules/ROOT/pages/5.0.adoc  |   1 +
 EN/modules/ROOT/pages/5.13.adoc | 173 ++++++++++++++++++++++++++++++++
 6 files changed, 350 insertions(+)
 create mode 100644 CN/modules/ROOT/pages/5.13.adoc
 create mode 100644 EN/modules/ROOT/pages/5.13.adoc

diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc
index f1a1baab..4f053fc5 100644
--- 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
index d9a776d9..2b6baec2 100644
--- 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
new file mode 100644
index 00000000..dca6e814
--- /dev/null
+++ 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
index 6b480fbd..5daac910 100644
--- 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
index 42144711..1cbd8ee1 100644
--- 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
new file mode 100644
index 00000000..39a87364
--- /dev/null
+++ 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].

From f3b911bb1e353184d27a52af072794d3d4355de2 Mon Sep 17 00:00:00 2001
From: messere1 <189848840+messere1@users.noreply.github.com>
Date: Wed, 26 Aug 2026 18:26:58 +0800
Subject: [PATCH 2/2] docs: clarify Pgpool Oracle SQL routing limits

Distinguish PostgreSQL-syntax load balancing from Oracle-mode connectivity, document primary routing on parse errors, and describe per-node routing validation.

Assisted-by: OpenAI:gpt-5
---
 CN/modules/ROOT/pages/5.13.adoc | 40 ++++++++++++++++++++++++++-------
 EN/modules/ROOT/pages/5.13.adoc | 40 ++++++++++++++++++++++++++-------
 2 files changed, 64 insertions(+), 16 deletions(-)

diff --git a/CN/modules/ROOT/pages/5.13.adoc b/CN/modules/ROOT/pages/5.13.adoc
index dca6e814..ecdd8e6a 100644
--- a/CN/modules/ROOT/pages/5.13.adoc
+++ b/CN/modules/ROOT/pages/5.13.adoc
@@ -27,13 +27,17 @@ Pgpool-II 是部署在数据库客户端与 IvorySQL 服务之间的中间件，
 |支持
 |`SHOW POOL_NODES` 正确识别主库和备库
 
-|只读查询负载均衡
-|支持
-|配置相同权重后，两个节点均收到 SELECT 查询
+|PostgreSQL 兼容语法的只读查询负载均衡
+|已验证所测试的查询
+|配置相同权重后，两个节点均收到所测试的 SELECT 查询；这不能证明 Oracle 专用语法支持负载均衡
 
 |Oracle 兼容会话
-|支持，存在注意事项
-|会话切换到 `ivorysql.compatible_mode = oracle` 后可通过 Pgpool-II 成功查询
+|已验证连通性
+|会话切换到 `ivorysql.compatible_mode = oracle` 后成功执行下文的 SELECT 示例；未测试 Oracle 专用语法的路由
+
+|Oracle 专用语法的负载均衡
+|未验证
+|在流复制模式下，Pgpool-II 解析器无法解析的语句会发送到主库，不参与负载均衡
 |===
 
 == 前提条件
@@ -148,7 +152,7 @@ SHOW POOL_NODES;
 SHOW POOL_PROCESSES;
 ----
 
-IvorySQL 5.4 验证中，Pgpool-II 将两个节点状态均报告为 `up`，角色正确识别为 `primary` 和 `standby`，复制延迟为 0。配置相同权重后，首轮 21 个读查询中，主库执行 9 个，备库执行 12 个。
+IvorySQL 5.4 验证中，Pgpool-II 将两个节点状态均报告为 `up`，角色正确识别为 `primary` 和 `standby`，复制延迟为 0。配置相同权重后，首轮 21 个读查询中，主库执行 9 个，备库执行 12 个。这些结果仅适用于所测试的 PostgreSQL 兼容 SELECT 查询，不适用于 Oracle 专用语法。
 
 == Oracle 兼容模式
 
@@ -160,12 +164,32 @@ SET ivorysql.compatible_mode = oracle;
 SELECT 'connected through Pgpool-II' AS status FROM dual;
 ----
 
-该查询已在 Pgpool-II 后端的 IvorySQL 主备环境中验证通过。
+该示例验证的是 Oracle 兼容会话的连通性和执行能力，而不是 Oracle 专用语法的负载均衡。`SELECT ... FROM dual` 在语法形式上仍是引用关系的 PostgreSQL 兼容 SELECT。修改 `ivorysql.compatible_mode` 会改变后端行为，但不会改变 Pgpool-II 的 SQL 解析器。
+
+[IMPORTANT]
+====
+Pgpool-II 4.7 使用 PostgreSQL 18 的 SQL 解析器，详见其 https://www.pgpool.net/docs/4.7/en/html/release-4-7-0.html[发行说明]。根据 https://www.pgpool.net/docs/4.7/en/html/runtime-config-load-balancing.html[负载均衡规则]，在本文采用的流复制模式下，Pgpool-II 无法解析的语句会发送到主库。因此，超出该解析器语法范围的 Oracle 专用语句即使配置了 `load_balance_mode = on`，也不会获得只读查询负载均衡能力。
+
+这并不表示 Oracle 兼容会话中的每一条查询都必须走主库：Pgpool-II 能够解析的查询仍需满足其他负载均衡条件。不能仅凭会话模式或执行成功就判断路由能力。
+====
+
+=== 检查应用的实际路由
+
+在测试环境中，在 `pgpool.conf` 中启用 https://www.pgpool.net/docs/4.7/en/html/runtime-config-logging.html#GUC-LOG-PER-NODE-STATEMENT[`log_per_node_statement`] 并重新加载配置：
+
+[source,ini]
+----
+log_per_node_statement = on
+----
+
+通过 Pgpool-II 分别执行应用中有代表性的 PostgreSQL 兼容查询和 Oracle 专用语句，再检查逐节点语句日志，确认实际发送目标。同时测试应用的事务及先写后读序列，因为语法解析并不是决定负载均衡资格的唯一条件。`SHOW POOL_NODES` 可辅助检查节点状态，但执行成功或已选定负载均衡节点，都不能证明某条语句实际在备库执行。
+
+在完成应用级路由验证前，不要依赖备库分担 Oracle 专用 SQL 的读取负载。若 SQL 文本包含敏感数据，应在测试结束后关闭语句日志。
 
 == 运维注意事项
 
 * 本文验证的是 IvorySQL PostgreSQL 兼容端点，不包括通过 `ivorysql.port` 代理 Oracle 客户端协议。
-* Pgpool-II 会解析 SQL 以决定路由位置。应测试应用使用的 Oracle 专用语法，并将必须读取最新数据的语句路由到主库。
+* 遵守上述 Oracle 专用语法的路由限制，并将必须读取最新数据的语句路由到主库。
 * 异步流复制可能从备库返回旧数据。应根据一致性要求配置延迟阈值或同步复制。
 * 不要在对外服务中使用 `trust` 认证。生产环境应启用 TLS、SCRAM、受限监听地址及最小权限监控账户。
 * 自动故障转移属于独立的高可用设计。启用前必须测试节点提升、隔离、客户端重试和脑裂防护。
diff --git a/EN/modules/ROOT/pages/5.13.adoc b/EN/modules/ROOT/pages/5.13.adoc
index 39a87364..a2020fb6 100644
--- a/EN/modules/ROOT/pages/5.13.adoc
+++ b/EN/modules/ROOT/pages/5.13.adoc
@@ -27,13 +27,17 @@ This guide was verified with IvorySQL 5.4 (PostgreSQL 18.4) and Pgpool-II 4.7.2
 |Supported
 |`SHOW POOL_NODES` identified the primary and standby correctly
 
-|Read-query load balancing
-|Supported
-|Both nodes received SELECT queries with equal configured weights
+|Read-query load balancing with PostgreSQL-compatible syntax
+|Verified for the tested queries
+|Both nodes received the tested SELECT queries with equal configured weights; this does not establish load balancing for Oracle-specific syntax
 
 |Oracle-compatible sessions
-|Supported with notes
-|A session switched to `ivorysql.compatible_mode = oracle` and queried through Pgpool-II successfully
+|Connectivity verified
+|A session switched to `ivorysql.compatible_mode = oracle` and executed the SELECT example below; Oracle-specific syntax routing was not tested
+
+|Load balancing of Oracle-specific syntax
+|Not verified
+|In streaming-replication mode, statements rejected by Pgpool-II's parser are sent to the primary, not load balanced
 |===
 
 == Prerequisites
@@ -148,7 +152,7 @@ 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.
+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. These results apply to the tested PostgreSQL-compatible SELECT queries, not to Oracle-specific syntax.
 
 == Oracle-compatible mode
 
@@ -160,12 +164,32 @@ 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.
+This example verifies connectivity and execution in an Oracle-compatible session, not load balancing of Oracle-specific syntax. Its `SELECT ... FROM dual` form is still a PostgreSQL-compatible SELECT referencing a relation. Changing `ivorysql.compatible_mode` changes the backend's behavior; it does not change Pgpool-II's SQL parser.
+
+[IMPORTANT]
+====
+Pgpool-II 4.7 uses the PostgreSQL 18 SQL parser, as documented in its https://www.pgpool.net/docs/4.7/en/html/release-4-7-0.html[release notes]. In this guide's streaming-replication mode, statements that Pgpool-II cannot parse are sent to the primary according to its https://www.pgpool.net/docs/4.7/en/html/runtime-config-load-balancing.html[load-balancing rules]. Oracle-specific syntax outside that parser's grammar therefore does not benefit from read-query load balancing, even with `load_balance_mode = on`.
+
+This does not mean every query in an Oracle-compatible session must go to the primary: a query that Pgpool-II can parse must still satisfy its other load-balancing conditions. Do not infer routing support from the session mode or successful execution alone.
+====
+
+=== Check routing for an application
+
+In a test environment, enable https://www.pgpool.net/docs/4.7/en/html/runtime-config-logging.html#GUC-LOG-PER-NODE-STATEMENT[`log_per_node_statement`] in `pgpool.conf` and reload the configuration:
+
+[source,ini]
+----
+log_per_node_statement = on
+----
+
+Run the application's representative PostgreSQL-compatible queries and Oracle-specific statements separately through Pgpool-II, then inspect the per-node statement logs to identify the actual destination. Test the application's transaction and write/read sequences as well; parsing alone does not determine load-balancing eligibility. `SHOW POOL_NODES` can help inspect node status, but successful execution and the selected load-balancing node are not proof that a particular statement ran on the standby.
+
+Until this application-level routing validation is complete, do not rely on standby read offloading for Oracle-specific SQL. Disable statement logging after testing if SQL text contains sensitive data.
 
 == 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.
+* Apply the Oracle-specific routing limitations above, 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.