Skip to content

Commit 04ab0f3

Browse files
committed
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>
1 parent 6068dc3 commit 04ab0f3

4 files changed

Lines changed: 116 additions & 0 deletions

File tree

CN/modules/ROOT/nav.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
*** xref:5.9.adoc[pgrouting]
5353
*** xref:5.10.adoc[system_stats]
5454
*** xref:5.11.adoc[pgtt]
55+
*** xref:5.12.adoc[pg_hint_plan]
5556
*** xref:5.14.adoc[pgnodemx]
5657
* 监控运维
5758
** xref:3.2.adoc[日常监控]

CN/modules/ROOT/pages/5.12.adoc

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
5+
= pg_hint_plan
6+
7+
== 概述
8+
pg_hint_plan 是一个 PostgreSQL 扩展,允许通过 SQL 语句中特殊的注释(称为"提示")来控制优化器选择的执行计划。它与 IvorySQL 完全兼容。
9+
10+
== 安装
11+
12+
=== 前置条件
13+
pg_hint_plan 需要在服务启动时加载,在 postgresql.conf 中添加:
14+
15+
[literal]
16+
----
17+
shared_preload_libraries = 'pg_hint_plan'
18+
----
19+
20+
=== 源码安装
21+
22+
[NOTE]
23+
请确保环境中已安装 **IvorySQL {ivorysql-version} 或以上版本**,且 `pg_config` 在 PATH 中。
24+
25+
[literal]
26+
----
27+
$ git clone https://github.com/ossc-db/pg_hint_plan.git
28+
$ cd pg_hint_plan
29+
$ make
30+
$ sudo make install
31+
----
32+
33+
== 创建扩展并验证
34+
35+
使用 psql 连接数据库,执行以下命令:
36+
37+
[literal]
38+
----
39+
ivorysql=# CREATE EXTENSION pg_hint_plan;
40+
CREATE EXTENSION
41+
42+
ivorysql=# SELECT * FROM pg_available_extensions WHERE name = 'pg_hint_plan';
43+
name | default_version | installed_version | comment
44+
--------------+-----------------+-------------------+---------------------------------
45+
pg_hint_plan | 1.7.0 | 1.7.0 | Give optimizer hints
46+
----
47+
48+
== 使用示例
49+
50+
提示以特殊注释的形式写在查询的开头。例如,强制对表 `t` 使用顺序扫描:
51+
52+
[literal]
53+
----
54+
ivorysql=# EXPLAIN SELECT /*+ SeqScan(t) */ * FROM t;
55+
----
56+
57+
完整支持的提示列表请参见 https://github.com/ossc-db/pg_hint_plan/blob/master/doc/pg_hint_plan.md[pg_hint_plan 文档]。

EN/modules/ROOT/nav.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
*** xref:5.9.adoc[pgrouting]
5353
*** xref:5.10.adoc[system_stats]
5454
*** xref:5.11.adoc[pgtt]
55+
*** xref:5.12.adoc[pg_hint_plan]
5556
*** xref:5.14.adoc[pgnodemx]
5657
* Monitor and O&M
5758
** xref:3.2.adoc[Monitoring]

EN/modules/ROOT/pages/5.12.adoc

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
5+
= pg_hint_plan
6+
7+
== Overview
8+
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.
9+
10+
== Installation
11+
12+
=== Prerequisites
13+
pg_hint_plan must be loaded at server start. Add it to `shared_preload_libraries` in `postgresql.conf`:
14+
15+
[literal]
16+
----
17+
shared_preload_libraries = 'pg_hint_plan'
18+
----
19+
20+
=== Source Code Installation
21+
22+
[NOTE]
23+
Please ensure that **IvorySQL {ivorysql-version} or above** is installed and `pg_config` is available in `PATH`.
24+
25+
[literal]
26+
----
27+
$ git clone https://github.com/ossc-db/pg_hint_plan.git
28+
$ cd pg_hint_plan
29+
$ make
30+
$ sudo make install
31+
----
32+
33+
== Create Extension and Verify
34+
35+
Connect to the database with psql and execute the following commands:
36+
37+
[literal]
38+
----
39+
ivorysql=# CREATE EXTENSION pg_hint_plan;
40+
CREATE EXTENSION
41+
42+
ivorysql=# SELECT * FROM pg_available_extensions WHERE name = 'pg_hint_plan';
43+
name | default_version | installed_version | comment
44+
--------------+-----------------+-------------------+---------------------------------
45+
pg_hint_plan | 1.7.0 | 1.7.0 | Give optimizer hints
46+
----
47+
48+
== Usage Example
49+
50+
Hints are written as special comments at the start of a query. For example, to force a sequential scan on table `t`:
51+
52+
[literal]
53+
----
54+
ivorysql=# EXPLAIN SELECT /*+ SeqScan(t) */ * FROM t;
55+
----
56+
57+
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.

0 commit comments

Comments
 (0)