From 04ab0f36f1d33cab3832b190603cceaf67388e74 Mon Sep 17 00:00:00 2001
From: jokerzsd <2701819133@qq.com>
Date: Wed, 9 Sep 2026 20:03:05 +0800
Subject: [PATCH] docs: add pg_hint_plan ecosystem component documentation

Add the pg_hint_plan adapter doc (overview, installation, usage) to the
Eco Component Adaption section, in both English and Chinese.

Closes #250

Signed-off-by: jokerzsd <2701819133@qq.com>
---
 CN/modules/ROOT/nav.adoc        |  1 +
 CN/modules/ROOT/pages/5.12.adoc | 57 +++++++++++++++++++++++++++++++++
 EN/modules/ROOT/nav.adoc        |  1 +
 EN/modules/ROOT/pages/5.12.adoc | 57 +++++++++++++++++++++++++++++++++
 4 files changed, 116 insertions(+)
 create mode 100644 CN/modules/ROOT/pages/5.12.adoc
 create mode 100644 EN/modules/ROOT/pages/5.12.adoc

diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc
index cc046246..40372d52 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.12.adoc[pg_hint_plan]
 *** xref:5.14.adoc[pgnodemx]
 * 监控运维
 ** xref:3.2.adoc[日常监控]
diff --git a/CN/modules/ROOT/pages/5.12.adoc b/CN/modules/ROOT/pages/5.12.adoc
new file mode 100644
index 00000000..d1d1a772
--- /dev/null
+++ b/CN/modules/ROOT/pages/5.12.adoc
@@ -0,0 +1,57 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+= pg_hint_plan
+
+== 概述
+pg_hint_plan 是一个 PostgreSQL 扩展，允许通过 SQL 语句中特殊的注释（称为"提示"）来控制优化器选择的执行计划。它与 IvorySQL 完全兼容。
+
+== 安装
+
+=== 前置条件
+pg_hint_plan 需要在服务启动时加载，在 postgresql.conf 中添加：
+
+[literal]
+----
+shared_preload_libraries = 'pg_hint_plan'
+----
+
+=== 源码安装
+
+[NOTE]
+请确保环境中已安装 **IvorySQL {ivorysql-version} 或以上版本**，且 `pg_config` 在 PATH 中。
+
+[literal]
+----
+$ git clone https://github.com/ossc-db/pg_hint_plan.git
+$ cd pg_hint_plan
+$ make
+$ sudo make install
+----
+
+== 创建扩展并验证
+
+使用 psql 连接数据库，执行以下命令：
+
+[literal]
+----
+ivorysql=# CREATE EXTENSION pg_hint_plan;
+CREATE EXTENSION
+
+ivorysql=# SELECT * FROM pg_available_extensions WHERE name = 'pg_hint_plan';
+  name        | default_version | installed_version | comment
+--------------+-----------------+-------------------+---------------------------------
+ pg_hint_plan | 1.7.0           | 1.7.0             | Give optimizer hints
+----
+
+== 使用示例
+
+提示以特殊注释的形式写在查询的开头。例如，强制对表 `t` 使用顺序扫描：
+
+[literal]
+----
+ivorysql=# EXPLAIN SELECT /*+ SeqScan(t) */ * FROM t;
+----
+
+完整支持的提示列表请参见 https://github.com/ossc-db/pg_hint_plan/blob/master/doc/pg_hint_plan.md[pg_hint_plan 文档]。
diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc
index 0f803fbb..7cd2415f 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.12.adoc[pg_hint_plan]
 *** xref:5.14.adoc[pgnodemx]
 * Monitor and O&M
 ** xref:3.2.adoc[Monitoring]
diff --git a/EN/modules/ROOT/pages/5.12.adoc b/EN/modules/ROOT/pages/5.12.adoc
new file mode 100644
index 00000000..cb491986
--- /dev/null
+++ b/EN/modules/ROOT/pages/5.12.adoc
@@ -0,0 +1,57 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+= pg_hint_plan
+
+== Overview
+pg_hint_plan is a PostgreSQL extension that lets you control the execution plan chosen by the optimizer using special comments called "hints" embedded in SQL statements. It is fully compatible with IvorySQL.
+
+== Installation
+
+=== Prerequisites
+pg_hint_plan must be loaded at server start. Add it to `shared_preload_libraries` in `postgresql.conf`:
+
+[literal]
+----
+shared_preload_libraries = 'pg_hint_plan'
+----
+
+=== Source Code Installation
+
+[NOTE]
+Please ensure that **IvorySQL {ivorysql-version} or above** is installed and `pg_config` is available in `PATH`.
+
+[literal]
+----
+$ git clone https://github.com/ossc-db/pg_hint_plan.git
+$ cd pg_hint_plan
+$ make
+$ sudo make install
+----
+
+== Create Extension and Verify
+
+Connect to the database with psql and execute the following commands:
+
+[literal]
+----
+ivorysql=# CREATE EXTENSION pg_hint_plan;
+CREATE EXTENSION
+
+ivorysql=# SELECT * FROM pg_available_extensions WHERE name = 'pg_hint_plan';
+  name        | default_version | installed_version | comment
+--------------+-----------------+-------------------+---------------------------------
+ pg_hint_plan | 1.7.0           | 1.7.0             | Give optimizer hints
+----
+
+== Usage Example
+
+Hints are written as special comments at the start of a query. For example, to force a sequential scan on table `t`:
+
+[literal]
+----
+ivorysql=# EXPLAIN SELECT /*+ SeqScan(t) */ * FROM t;
+----
+
+See the https://github.com/ossc-db/pg_hint_plan/blob/master/doc/pg_hint_plan.md[pg_hint_plan documentation] for the full list of supported hints.