From 8e43eb6e7a36386acda038a5928735d98ac9754d Mon Sep 17 00:00:00 2001
From: Oreo Yang <2167young@163.com>
Date: Fri, 3 Apr 2026 15:21:32 +0800
Subject: [PATCH 1/3] docs: add pg_hint_plan adaptation documentation

Add bilingual documentation for pg_hint_plan extension with installation guide, hint types, usage examples, and IvorySQL compatibility notes.
---
 CN/modules/ROOT/nav.adoc                      |   1 +
 .../ecosystem_components/pg_hint_plan.adoc    | 213 ++++++++++++++++++
 EN/modules/ROOT/nav.adoc                      |   1 +
 .../ecosystem_components/pg_hint_plan.adoc    | 212 +++++++++++++++++
 4 files changed, 427 insertions(+)
 create mode 100644 CN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
 create mode 100644 EN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc

diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc
index 4764443..ea53307 100644
--- a/CN/modules/ROOT/nav.adoc
+++ b/CN/modules/ROOT/nav.adoc
@@ -57,6 +57,7 @@
 *** xref:master/ecosystem_components/pgbouncer.adoc[pgbouncer]
 *** xref:master/ecosystem_components/pg_curl.adoc[pg_curl]
 *** xref:master/ecosystem_components/pg_textsearch.adoc[pg_textsearch]
+*** xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan]
 * 监控运维
 ** xref:master/getting-started/daily_monitoring.adoc[日常监控]
 ** xref:master/getting-started/daily_maintenance.adoc[日常维护]
diff --git a/CN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc b/CN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
new file mode 100644
index 0000000..eb7ec13
--- /dev/null
+++ b/CN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
@@ -0,0 +1,213 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+= pg_hint_plan
+
+== 概述
+
+pg_hint_plan 是一个扩展，允许通过 SQL 注释中的 hints 来控制 PostgreSQL/IvorySQL 的执行计划。它能够在不修改 SQL 逻辑的情况下优化查询性能，在 PostgreSQL 和 Oracle 兼容模式下均可正常工作。
+
+本项目针对 IvorySQL 5 进行适配，源码仓库位于 <https://github.com/ossc-db/pg_hint_plan>。
+
+== 安装
+
+[TIP]
+源码安装环境为 Ubuntu 24.04(x86_64)，环境中已经安装了IvorySQL 5及以上版本，安装路径为/usr/ivory-5
+
+=== 源码安装
+
+[literal]
+----
+# 克隆 PG18 分支源码
+
+git clone --branch PG18 https://github.com/ossc-db/pg_hint_plan.git
+cd pg_hint_plan
+
+# 编译安装插件
+make PG_CONFIG=/usr/ivory-5/bin/pg_config
+make PG_CONFIG=/usr/ivory-5/bin/pg_config install
+
+----
+
+=== 修改数据库配置文件
+
+修改 ivorysql.conf 文件，添加 pg_hint_plan 到 shared_preload_libraries：
+
+[literal]
+----
+shared_preload_libraries = 'gb18030_2022, liboracle_parser, ivorysql_ora, pg_hint_plan'
+----
+
+重启数据库后配置生效。
+
+=== 加载扩展
+
+[literal]
+----
+postgres=# LOAD 'pg_hint_plan';
+LOAD
+----
+
+== Hint 类型
+
+pg_hint_plan 提供了多种类型的 hints 来控制查询执行计划的不同方面。
+
+=== 扫描方法 Hints
+
+指定表扫描方法的 hints：
+
+* `SeqScan(table)` - 顺序扫描
+* `IndexScan(table[ index])` - 索引扫描，可指定索引名
+* `BitmapScan(table[ index])` - 位图扫描，可指定索引名
+* `TidScan(table)` - TID 扫描
+
+否定形式的 hints（禁止使用某种扫描方法）：
+
+* `NoSeqScan(table)`
+* `NoIndexScan(table)`
+* `NoBitmapScan(table)`
+* `NoTidScan(table)`
+
+=== 连接方法 Hints
+
+指定表连接方法的 hints：
+
+* `HashJoin(table table[ table...])` - 哈希连接
+* `NestedLoop(table table[ table...])` - 嵌套循环连接
+* `MergeJoin(table table[ table...])` - 合并连接
+
+否定形式的 hints：
+
+* `NoHashJoin(table table)`
+* `NoNestedLoop(table table)`
+* `NoMergeJoin(table table)`
+
+=== 连接顺序 Hints
+
+* `Leading(table table[ table...])` - 指定连接顺序，表按顺序连接
+
+=== 并行执行 Hints
+
+* `Parallel(table count[ workers])` - 设置并行工作进程数量
+    * `count` - 是否使用并行（0 表示不使用，1 表示使用）
+    * `workers` - 并行工作进程数量（可选，默认值为规划器计算的值）
+
+=== 其他 Hints
+
+* `Set(enable_*)` - 设置 GUC 参数
+* `Rows(table table[ table...] correction)` - 修正行数估计值
+
+== 使用示例
+
+=== 基本用法示例
+
+使用 HashJoin 和 SeqScan hints：
+
+[literal]
+----
+postgres=# /*+
+   HashJoin(a b)
+   SeqScan(a)
+*/
+EXPLAIN SELECT *
+FROM pgbench_branches b
+JOIN pgbench_accounts a ON b.bid = a.bid
+ORDER BY a.aid;
+----
+
+=== 复杂多 Hint 示例
+
+组合使用多个 hints 来控制复杂查询的执行计划：
+
+[literal]
+----
+postgres=# /*+
+   NestedLoop(t1 t2)
+   IndexScan(t2 t2_pkey)
+   MergeJoin(t1 t2 t3)
+   Leading(t1 t2 t3)
+*/
+EXPLAIN SELECT * FROM table1 t1
+JOIN table2 t2 ON t1.id = t2.id
+JOIN table3 t3 ON t2.id = t3.id;
+----
+
+=== 并行执行示例
+
+为多个表设置并行度和连接方法：
+
+[literal]
+----
+postgres=# /*+
+   Parallel(t1 3)
+   Parallel(t2 5)
+   HashJoin(t1 t2)
+*/
+EXPLAIN SELECT * FROM large_table1 t1
+JOIN large_table2 t2 ON t1.id = t2.id;
+----
+
+=== 指定索引扫描示例
+
+强制使用特定索引进行扫描：
+
+[literal]
+----
+postgres=# /*+
+   IndexScan(employees emp_name_idx)
+*/
+EXPLAIN SELECT * FROM employees
+WHERE last_name = 'SMITH';
+----
+
+== Hint 表（可选功能）
+
+pg_hint_plan 提供了一个可选的 hint 表功能，可以在表中持久化存储 hints。
+
+=== 创建 Hint 表
+
+[literal]
+----
+postgres=# CREATE TABLE hint_plan.hints (
+    id serial PRIMARY KEY,
+    norm_query_string text NOT NULL,
+    application_name text,
+    hints text NOT NULL,
+    CONSTRAINT hint_plan_hints_norm_query_string_key UNIQUE (norm_query_string, application_name)
+);
+----
+
+=== 插入 Hints
+
+[literal]
+----
+postgres=# INSERT INTO hint_plan.hints (norm_query_string, application_name, hints)
+VALUES (
+    'SELECT * FROM table1 WHERE id = ?;',
+    'psql',
+    'SeqScan(table1)'
+);
+----
+
+通过 hint 表，可以为特定查询自动应用 hints，无需修改 SQL 语句。
+
+== IvorySQL 兼容性
+
+=== Oracle 兼容模式
+
+pg_hint_plan 在 PostgreSQL 和 Oracle 兼容模式下均可正常工作。hint 语法保持一致，并与 IvorySQL 特有的数据类型（VARCHAR2、NUMBER 等）兼容。
+
+=== Oracle 模式示例
+
+[literal]
+----
+-- 连接到 1521 端口（Oracle 模式）
+postgres=# /*+
+   IndexScan(employees emp_name_idx)
+*/
+SELECT * FROM employees WHERE last_name = 'SMITH';
+----
+
+在 Oracle 兼容模式下，hint 的使用方法与 PostgreSQL 模式完全相同，可以正常控制包含 IvorySQL 特有数据类型和语法的查询执行计划。
+
diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc
index 66c385e..bdd76bd 100644
--- a/EN/modules/ROOT/nav.adoc
+++ b/EN/modules/ROOT/nav.adoc
@@ -57,6 +57,7 @@
 *** xref:master/ecosystem_components/pgbouncer.adoc[pgbouncer]
 *** xref:master/ecosystem_components/pg_curl.adoc[pg_curl]
 *** xref:master/ecosystem_components/pg_textsearch.adoc[pg_textsearch]
+*** xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan]
 * Monitor and O&M
 ** xref:master/getting-started/daily_monitoring.adoc[Monitoring]
 ** xref:master/getting-started/daily_maintenance.adoc[Maintenance]
diff --git a/EN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc b/EN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
new file mode 100644
index 0000000..649ed37
--- /dev/null
+++ b/EN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
@@ -0,0 +1,212 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+= pg_hint_plan
+
+== Overview
+
+pg_hint_plan is an extension that allows controlling PostgreSQL/IvorySQL execution plans using SQL comment hints. It optimizes query performance without modifying SQL logic and works in both PostgreSQL and Oracle compatibility modes.
+
+This project is adapted for IvorySQL 5, based on the PG18 branch. The source repository is located at <https://github.com/ossc-db/pg_hint_plan>.
+
+== Installation
+
+[TIP]
+The source installation environment is Ubuntu 24.04(x86_64), with IvorySQL 5 or above installed at /usr/ivory-5
+
+=== Install from Source
+
+[literal]
+----
+# Clone PG18 branch source code
+
+git clone --branch PG18 https://github.com/ossc-db/pg_hint_plan.git
+cd pg_hint_plan
+
+# Compile and install the extension
+make PG_CONFIG=/usr/ivory-5/bin/pg_config
+make PG_CONFIG=/usr/ivory-5/bin/pg_config install
+
+----
+
+=== Modify Database Configuration File
+
+Modify the ivorysql.conf file to add pg_hint_plan to shared_preload_libraries:
+
+[literal]
+----
+shared_preload_libraries = 'gb18030_2022, liboracle_parser, ivorysql_ora, pg_hint_plan'
+----
+
+Restart the database for the configuration to take effect.
+
+=== Load Extension
+
+[literal]
+----
+postgres=# LOAD 'pg_hint_plan';
+LOAD
+----
+
+== Hint Types
+
+pg_hint_plan provides various types of hints to control different aspects of query execution plans.
+
+=== Scan Method Hints
+
+Hints specifying table scan methods:
+
+* `SeqScan(table)` - Sequential scan
+* `IndexScan(table[ index])` - Index scan, optionally specifying index name
+* `BitmapScan(table[ index])` - Bitmap scan, optionally specifying index name
+* `TidScan(table)` - TID scan
+
+Negative form hints (prohibit using a specific scan method):
+
+* `NoSeqScan(table)`
+* `NoIndexScan(table)`
+* `NoBitmapScan(table)`
+* `NoTidScan(table)`
+
+=== Join Method Hints
+
+Hints specifying table join methods:
+
+* `HashJoin(table table[ table...])` - Hash join
+* `NestedLoop(table table[ table...])` - Nested loop join
+* `MergeJoin(table table[ table...])` - Merge join
+
+Negative form hints:
+
+* `NoHashJoin(table table)`
+* `NoNestedLoop(table table)`
+* `NoMergeJoin(table table)`
+
+=== Join Order Hints
+
+* `Leading(table table[ table...])` - Specify join order, tables are joined in sequence
+
+=== Parallel Execution Hints
+
+* `Parallel(table count[ workers])` - Set number of parallel worker processes
+    * `count` - Whether to use parallel (0 means no, 1 means yes)
+    * `workers` - Number of parallel worker processes (optional, defaults to planner-calculated value)
+
+=== Other Hints
+
+* `Set(enable_*)` - Set GUC parameters
+* `Rows(table table[ table...] correction)` - Correct rows estimate
+
+== Usage Examples
+
+=== Basic Usage Example
+
+Using HashJoin and SeqScan hints:
+
+[literal]
+----
+postgres=# /*+
+   HashJoin(a b)
+   SeqScan(a)
+*/
+EXPLAIN SELECT *
+FROM pgbench_branches b
+JOIN pgbench_accounts a ON b.bid = a.bid
+ORDER BY a.aid;
+----
+
+=== Complex Multi-Hint Example
+
+Combining multiple hints to control execution plan for complex queries:
+
+[literal]
+----
+postgres=# /*+
+   NestedLoop(t1 t2)
+   IndexScan(t2 t2_pkey)
+   MergeJoin(t1 t2 t3)
+   Leading(t1 t2 t3)
+*/
+EXPLAIN SELECT * FROM table1 t1
+JOIN table2 t2 ON t1.id = t2.id
+JOIN table3 t3 ON t2.id = t3.id;
+----
+
+=== Parallel Execution Example
+
+Setting parallel degree and join methods for multiple tables:
+
+[literal]
+----
+postgres=# /*+
+   Parallel(t1 3)
+   Parallel(t2 5)
+   HashJoin(t1 t2)
+*/
+EXPLAIN SELECT * FROM large_table1 t1
+JOIN large_table2 t2 ON t1.id = t2.id;
+----
+
+=== Specify Index Scan Example
+
+Force scanning using a specific index:
+
+[literal]
+----
+postgres=# /*+
+   IndexScan(employees emp_name_idx)
+*/
+EXPLAIN SELECT * FROM employees
+WHERE last_name = 'SMITH';
+----
+
+== Hint Table (Optional Feature)
+
+pg_hint_plan provides an optional hint table feature for persistently storing hints.
+
+=== Create Hint Table
+
+[literal]
+----
+postgres=# CREATE TABLE hint_plan.hints (
+    id serial PRIMARY KEY,
+    norm_query_string text NOT NULL,
+    application_name text,
+    hints text NOT NULL,
+    CONSTRAINT hint_plan_hints_norm_query_string_key UNIQUE (norm_query_string, application_name)
+);
+----
+
+=== Insert Hints
+
+[literal]
+----
+postgres=# INSERT INTO hint_plan.hints (norm_query_string, application_name, hints)
+VALUES (
+    'SELECT * FROM table1 WHERE id = ?;',
+    'psql',
+    'SeqScan(table1)'
+);
+----
+
+Through the hint table, hints can be automatically applied to specific queries without modifying SQL statements.
+
+== IvorySQL Compatibility
+
+=== Oracle Compatibility Mode
+
+pg_hint_plan works in both PostgreSQL and Oracle compatibility modes. The hint syntax remains consistent and is compatible with IvorySQL-specific data types (VARCHAR2, NUMBER, etc.).
+
+=== Oracle Mode Example
+
+[literal]
+----
+-- Connect to port 1521 (Oracle mode)
+postgres=# /*+
+   IndexScan(employees emp_name_idx)
+*/
+SELECT * FROM employees WHERE last_name = 'SMITH';
+----
+
+In Oracle compatibility mode, hint usage is identical to PostgreSQL mode and can normally control query execution plans containing IvorySQL-specific data types and syntax.

From 30c9a8c1490953b60afdd6d09d8b4b297ec9a855 Mon Sep 17 00:00:00 2001
From: Oreo Yang <2167young@163.com>
Date: Wed, 8 Apr 2026 15:29:53 +0800
Subject: [PATCH 2/3] docs: add pg_hint_plan to ecosystem_overview.adoc

Add pg_hint_plan entry to the ecosystem plugin compatibility list in both Chinese and English documentation.
---
 .../pages/master/ecosystem_components/ecosystem_overview.adoc    | 1 +
 .../pages/master/ecosystem_components/ecosystem_overview.adoc    | 1 +
 2 files changed, 2 insertions(+)

diff --git a/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc b/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc
index 8c63543..d17d3e9 100644
--- a/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc
+++ b/CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc
@@ -25,6 +25,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
 | 12 | xref:master/ecosystem_components/pg_stat_monitor.adoc[pg_stat_monitor] | 2.3.1 | 收集性能统计数据，并通过统一视图和直方图形式直观展示查询性能指标。 | 性能监控
 | 13 | xref:master/ecosystem_components/pg_partman.adoc[pg_partman] | 5.2 | 辅助管理原生分区表，自动创建、维护、清理分区子表 | 海量数据存储管理
 | 14 | xref:master/ecosystem_components/pg_curl.adoc[pg_curl] | 2.4 | 基于 libcurl 的网络传输扩展，支持 HTTP/HTTPS、FTP、SMTP、IMAP 等二十余种协议，可在 SQL 中完成各类网络数据传输操作 | REST API 集成、邮件发送、文件传输、外部系统通知
+| 15 | xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan] | PG18 | 通过SQL注释中的hints控制执行计划，在不修改SQL逻辑的情况下优化查询性能 | 查询性能优化、执行计划调优、数据库性能分析
 |====
 
 这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。
diff --git a/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc b/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc
index f328c5f..d2fb461 100644
--- a/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc
+++ b/EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc
@@ -26,6 +26,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
 |*12*| xref:master/ecosystem_components/pg_stat_monitor.adoc[pg_stat_monitor] | 2.3.1 | Collects performance statistics and provides query performance insights in a single view and graphically in histogram. | Performance monitoring
 |*13*| xref:master/ecosystem_components/pg_partman.adoc[pg_partman] | 5.2 | Automates the creation, maintenance, and cleanup of native partition subtables. | Large-Scale Data Storage Management
 |*14*| xref:master/ecosystem_components/pg_curl.adoc[pg_curl] | 2.4 | A libcurl-based network transfer extension supporting HTTP/HTTPS, FTP, SMTP, IMAP, and 20+ other protocols, enabling network data transfer operations directly in SQL | REST API integration, email sending, file transfer, external system notifications
+|*15*| xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan] | PG18 | Controls execution plans via SQL comment hints, optimizing query performance without modifying SQL logic | Query performance optimization, execution plan tuning, database performance analysis
 |====
 
 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.

From 9a1c30a3cb981211c031251f54141532288ceabb Mon Sep 17 00:00:00 2001
From: Oreo Yang <2167young@163.com>
Date: Wed, 8 Apr 2026 15:39:37 +0800
Subject: [PATCH 3/3] docs: simplify pg_hint_plan overview section

Remove redundant adaptation and repository information from the overview to keep it concise.
---
 .../ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc     | 1 -
 .../ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc     | 1 -
 2 files changed, 2 deletions(-)

diff --git a/CN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc b/CN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
index eb7ec13..c04a24e 100644
--- a/CN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
+++ b/CN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
@@ -8,7 +8,6 @@
 
 pg_hint_plan 是一个扩展，允许通过 SQL 注释中的 hints 来控制 PostgreSQL/IvorySQL 的执行计划。它能够在不修改 SQL 逻辑的情况下优化查询性能，在 PostgreSQL 和 Oracle 兼容模式下均可正常工作。
 
-本项目针对 IvorySQL 5 进行适配，源码仓库位于 <https://github.com/ossc-db/pg_hint_plan>。
 
 == 安装
 
diff --git a/EN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc b/EN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
index 649ed37..73889fa 100644
--- a/EN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
+++ b/EN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc
@@ -8,7 +8,6 @@
 
 pg_hint_plan is an extension that allows controlling PostgreSQL/IvorySQL execution plans using SQL comment hints. It optimizes query performance without modifying SQL logic and works in both PostgreSQL and Oracle compatibility modes.
 
-This project is adapted for IvorySQL 5, based on the PG18 branch. The source repository is located at <https://github.com/ossc-db/pg_hint_plan>.
 
 == Installation