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

Author: messere1

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、受限监听地址及最小权限监控账户。
 * 自动故障转移属于独立的高可用设计。启用前必须测试节点提升、隔离、客户端重试和脑裂防护。

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.