Skip to content

Commit 531848c

Browse files
gaoxueyugaoxueyu
authored
Merge pull request #248 from OreoYang/ecos/pg_hint_plan
docs: add pg_hint_plan adaptation documentation
2 parents 1083f2a + 9a1c30a commit 531848c

File tree

6 files changed

+427
-0
lines changed

6 files changed

+427
-0
lines changed

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
*** xref:master/ecosystem_components/pgbouncer.adoc[pgbouncer]
5858
*** xref:master/ecosystem_components/pg_curl.adoc[pg_curl]
5959
*** xref:master/ecosystem_components/pg_textsearch.adoc[pg_textsearch]
60+
*** xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan]
6061
* 监控运维
6162
** xref:master/getting-started/daily_monitoring.adoc[日常监控]
6263
** xref:master/getting-started/daily_maintenance.adoc[日常维护]

‎CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
2525
| 12 | xref:master/ecosystem_components/pg_stat_monitor.adoc[pg_stat_monitor] | 2.3.1 | 收集性能统计数据，并通过统一视图和直方图形式直观展示查询性能指标。 | 性能监控
2626
| 13 | xref:master/ecosystem_components/pg_partman.adoc[pg_partman] | 5.2 | 辅助管理原生分区表，自动创建、维护、清理分区子表 | 海量数据存储管理
2727
| 14 | xref:master/ecosystem_components/pg_curl.adoc[pg_curl] | 2.4 | 基于 libcurl 的网络传输扩展，支持 HTTP/HTTPS、FTP、SMTP、IMAP 等二十余种协议，可在 SQL 中完成各类网络数据传输操作 | REST API 集成、邮件发送、文件传输、外部系统通知
28+
| 15 | xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan] | PG18 | 通过SQL注释中的hints控制执行计划，在不修改SQL逻辑的情况下优化查询性能 | 查询性能优化、执行计划调优、数据库性能分析
2829
|====
2930

3031
这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。

‎CN/modules/ROOT/pages/master/ecosystem_components/pg_hint_plan.adoc‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
5+
= pg_hint_plan
6+
7+
== 概述
8+
9+
pg_hint_plan 是一个扩展，允许通过 SQL 注释中的 hints 来控制 PostgreSQL/IvorySQL 的执行计划。它能够在不修改 SQL 逻辑的情况下优化查询性能，在 PostgreSQL 和 Oracle 兼容模式下均可正常工作。
10+
11+
12+
== 安装
13+
14+
[TIP]
15+
源码安装环境为 Ubuntu 24.04(x86_64)，环境中已经安装了IvorySQL 5及以上版本，安装路径为/usr/ivory-5
16+
17+
=== 源码安装
18+
19+
[literal]
20+
----
21+
# 克隆 PG18 分支源码
22+
23+
git clone --branch PG18 https://github.com/ossc-db/pg_hint_plan.git
24+
cd pg_hint_plan
25+
26+
# 编译安装插件
27+
make PG_CONFIG=/usr/ivory-5/bin/pg_config
28+
make PG_CONFIG=/usr/ivory-5/bin/pg_config install
29+
30+
----
31+
32+
=== 修改数据库配置文件
33+
34+
修改 ivorysql.conf 文件，添加 pg_hint_plan 到 shared_preload_libraries：
35+
36+
[literal]
37+
----
38+
shared_preload_libraries = 'gb18030_2022, liboracle_parser, ivorysql_ora, pg_hint_plan'
39+
----
40+
41+
重启数据库后配置生效。
42+
43+
=== 加载扩展
44+
45+
[literal]
46+
----
47+
postgres=# LOAD 'pg_hint_plan';
48+
LOAD
49+
----
50+
51+
== Hint 类型
52+
53+
pg_hint_plan 提供了多种类型的 hints 来控制查询执行计划的不同方面。
54+
55+
=== 扫描方法 Hints
56+
57+
指定表扫描方法的 hints：
58+
59+
* `SeqScan(table)` - 顺序扫描
60+
* `IndexScan(table[ index])` - 索引扫描，可指定索引名
61+
* `BitmapScan(table[ index])` - 位图扫描，可指定索引名
62+
* `TidScan(table)` - TID 扫描
63+
64+
否定形式的 hints（禁止使用某种扫描方法）：
65+
66+
* `NoSeqScan(table)`
67+
* `NoIndexScan(table)`
68+
* `NoBitmapScan(table)`
69+
* `NoTidScan(table)`
70+
71+
=== 连接方法 Hints
72+
73+
指定表连接方法的 hints：
74+
75+
* `HashJoin(table table[ table...])` - 哈希连接
76+
* `NestedLoop(table table[ table...])` - 嵌套循环连接
77+
* `MergeJoin(table table[ table...])` - 合并连接
78+
79+
否定形式的 hints：
80+
81+
* `NoHashJoin(table table)`
82+
* `NoNestedLoop(table table)`
83+
* `NoMergeJoin(table table)`
84+
85+
=== 连接顺序 Hints
86+
87+
* `Leading(table table[ table...])` - 指定连接顺序，表按顺序连接
88+
89+
=== 并行执行 Hints
90+
91+
* `Parallel(table count[ workers])` - 设置并行工作进程数量
92+
* `count` - 是否使用并行（0 表示不使用，1 表示使用）
93+
* `workers` - 并行工作进程数量（可选，默认值为规划器计算的值）
94+
95+
=== 其他 Hints
96+
97+
* `Set(enable_*)` - 设置 GUC 参数
98+
* `Rows(table table[ table...] correction)` - 修正行数估计值
99+
100+
== 使用示例
101+
102+
=== 基本用法示例
103+
104+
使用 HashJoin 和 SeqScan hints：
105+
106+
[literal]
107+
----
108+
postgres=# /*+
109+
HashJoin(a b)
110+
SeqScan(a)
111+
*/
112+
EXPLAIN SELECT *
113+
FROM pgbench_branches b
114+
JOIN pgbench_accounts a ON b.bid = a.bid
115+
ORDER BY a.aid;
116+
----
117+
118+
=== 复杂多 Hint 示例
119+
120+
组合使用多个 hints 来控制复杂查询的执行计划：
121+
122+
[literal]
123+
----
124+
postgres=# /*+
125+
NestedLoop(t1 t2)
126+
IndexScan(t2 t2_pkey)
127+
MergeJoin(t1 t2 t3)
128+
Leading(t1 t2 t3)
129+
*/
130+
EXPLAIN SELECT * FROM table1 t1
131+
JOIN table2 t2 ON t1.id = t2.id
132+
JOIN table3 t3 ON t2.id = t3.id;
133+
----
134+
135+
=== 并行执行示例
136+
137+
为多个表设置并行度和连接方法：
138+
139+
[literal]
140+
----
141+
postgres=# /*+
142+
Parallel(t1 3)
143+
Parallel(t2 5)
144+
HashJoin(t1 t2)
145+
*/
146+
EXPLAIN SELECT * FROM large_table1 t1
147+
JOIN large_table2 t2 ON t1.id = t2.id;
148+
----
149+
150+
=== 指定索引扫描示例
151+
152+
强制使用特定索引进行扫描：
153+
154+
[literal]
155+
----
156+
postgres=# /*+
157+
IndexScan(employees emp_name_idx)
158+
*/
159+
EXPLAIN SELECT * FROM employees
160+
WHERE last_name = 'SMITH';
161+
----
162+
163+
== Hint 表（可选功能）
164+
165+
pg_hint_plan 提供了一个可选的 hint 表功能，可以在表中持久化存储 hints。
166+
167+
=== 创建 Hint 表
168+
169+
[literal]
170+
----
171+
postgres=# CREATE TABLE hint_plan.hints (
172+
id serial PRIMARY KEY,
173+
norm_query_string text NOT NULL,
174+
application_name text,
175+
hints text NOT NULL,
176+
CONSTRAINT hint_plan_hints_norm_query_string_key UNIQUE (norm_query_string, application_name)
177+
);
178+
----
179+
180+
=== 插入 Hints
181+
182+
[literal]
183+
----
184+
postgres=# INSERT INTO hint_plan.hints (norm_query_string, application_name, hints)
185+
VALUES (
186+
'SELECT * FROM table1 WHERE id = ?;',
187+
'psql',
188+
'SeqScan(table1)'
189+
);
190+
----
191+
192+
通过 hint 表，可以为特定查询自动应用 hints，无需修改 SQL 语句。
193+
194+
== IvorySQL 兼容性
195+
196+
=== Oracle 兼容模式
197+
198+
pg_hint_plan 在 PostgreSQL 和 Oracle 兼容模式下均可正常工作。hint 语法保持一致，并与 IvorySQL 特有的数据类型（VARCHAR2、NUMBER 等）兼容。
199+
200+
=== Oracle 模式示例
201+
202+
[literal]
203+
----
204+
-- 连接到 1521 端口（Oracle 模式）
205+
postgres=# /*+
206+
IndexScan(employees emp_name_idx)
207+
*/
208+
SELECT * FROM employees WHERE last_name = 'SMITH';
209+
----
210+
211+
在 Oracle 兼容模式下，hint 的使用方法与 PostgreSQL 模式完全相同，可以正常控制包含 IvorySQL 特有数据类型和语法的查询执行计划。
212+

‎EN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
*** xref:master/ecosystem_components/pgbouncer.adoc[pgbouncer]
5858
*** xref:master/ecosystem_components/pg_curl.adoc[pg_curl]
5959
*** xref:master/ecosystem_components/pg_textsearch.adoc[pg_textsearch]
60+
*** xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan]
6061
* Monitor and O&M
6162
** xref:master/getting-started/daily_monitoring.adoc[Monitoring]
6263
** xref:master/getting-started/daily_maintenance.adoc[Maintenance]

‎EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
2626
|*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
2727
|*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
2828
|*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
29+
|*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
2930
|====
3031

3132
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.

0 commit comments

Comments
 (0)