Skip to content

Commit cb3865c

Browse files
hs-liuxhhs-liuxh
committed
add: pg_profile
1 parent b5f1ec8 commit cb3865c

4 files changed

Lines changed: 292 additions & 0 deletions

File tree

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
3434
| 21 | xref:master/ecosystem_components/pg_show_plans.adoc[pg_show_plans] | 2.1 | 显示当前所有正在运行的 SQL 语句的执行计划，支持 TEXT、JSON、YAML 等多种输出格式 | 查询性能诊断、实时执行计划监控、慢查询分析
3535
| 22 | xref:master/ecosystem_components/pg_bulkload.adoc[pg_bulkload] | 3.1.23 | 为IvorySQL提供高速数据载入工具，可以跳过PG的共享缓存直接将数据导入表中 | 海量数据初始加载，历史数据归档，跨库迁移
3636
| 23 | xref:master/ecosystem_components/pg_bigm.adoc[pg_bigm] | 1.2 | 为 IvorySQL 提供二元分词全文检索能力，适配中日韩文本，快速实现模糊检索与相似度查询 | 中日韩文内容、商品、地址类文字搜索场景
37+
| 24 | xref:master/ecosystem_components/pg_profile.adoc[pg_profile] | 4.11 | 收集数据库资源密集型活动的统计，基于两次采样点的差量分析生成历史负载报告，帮助定位性能瓶颈 | 数据库性能分析
3738
|====
3839

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

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

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
5+
= pg_profile
6+
7+
== 概述
8+
pg_profile 是一个用于 PostgreSQL 数据库性能分析的扩展工具，主要用于统计目标数据库中的资源密集型活动，帮助用户深入了解数据库运行状态、找出性能瓶颈并进行优化。它的报告本质上是“两个采样点的差量分析”，得出采样间隔内的增量负载，采样点序号从 1 开始计数。
9+
10+
pg_profile 硬依赖 dblink 与 plpgsql（其自身完全由 SQL 和 PL/pgSQL 编写，无需任何外部库或软件）；此外，建议安装 pg_stat_statements 扩展，以便在报告中获取 SQL 语句级别的统计信息。pg_profile 的版本与 PostgreSQL 的版本强相关，当前最高支持到 PG 18，具体的版本支持情况请查看 pg_profile 官方 github 仓库的 README.
11+
12+
IvorySQL 的 PG 模式和 Oracle 兼容模式都已经适配 pg_profile。需要注意的是，在 Oracle 兼容模式下，pg_profile 在编译前，需要手动修改扩展源码的 control.tpl 文件，增加一个配置项 `pg_dialect = true` ，否则无法正常安装。
13+
14+
项目地址：<https://github.com/zubkov-andrei/pg_profile>
15+
16+
开源协议：PostgreSQL License
17+
18+
== 安装启用
19+
20+
=== 源码编译
21+
IvorySQL 的 Oracle 兼容模式下安装 pg_profile，需要先修改 pg_profile 的 control.tpl 文件，增加 `pg_dialect` 配置项：
22+
[literal]
23+
----
24+
# pg_profile/control.tpl
25+
pg_dialect = true
26+
----
27+
28+
执行源码编译和安装：
29+
[literal]
30+
----
31+
# 构建并安装 pg_profile 及其依赖扩展
32+
make -C contrib/dblink install
33+
make -C contrib/pg_stat_statements install
34+
make -C contrib/pg_profile install
35+
----
36+
37+
安装产物为 `pg_profile.control` 与 `pg_profile--4.11.sql`。IvorySQL 的 Oracle 兼容模式下，可检查生成的 `pg_profile.control` 文件已携带 `pg_dialect` 声明：
38+
[literal]
39+
----
40+
default_version = '4.11'
41+
requires = 'dblink,plpgsql'
42+
superuser = false
43+
44+
pg_dialect = true
45+
----
46+
47+
=== 修改配置
48+
pg_profile 依赖的 pg_stat_statements 必须通过 `shared_preload_libraries` 在服务启动时加载。
49+
50+
编辑 `ivorysql.conf` ，在 `shared_preload_libraries` 配置项末尾追加 `pg_stat_statements`：
51+
[literal]
52+
----
53+
# ivorysql.conf
54+
shared_preload_libraries = 'liboracle_parser, ivorysql_ora, pg_stat_statements'
55+
----
56+
57+
=== 重启服务
58+
[literal]
59+
----
60+
pg_ctl -D $PGDATA restart
61+
----
62+
63+
=== 安装扩展
64+
PG 模式与 Oracle 模式会话下命令相同：
65+
[literal]
66+
----
67+
CREATE SCHEMA profile;
68+
CREATE SCHEMA dblink;
69+
CREATE SCHEMA statements;
70+
CREATE EXTENSION dblink SCHEMA dblink;
71+
CREATE EXTENSION pg_stat_statements SCHEMA statements;
72+
CREATE EXTENSION pg_profile SCHEMA profile;
73+
74+
SELECT extname, extversion FROM pg_extension WHERE extname = 'pg_profile';
75+
extname | extversion
76+
------------+------------
77+
pg_profile | 4.11
78+
----
79+
80+
在 Oracle 兼容模式下，可执行下面的查询语句确认 pg_profile 的扩展函数已被固定到 PG 语法解析器：
81+
[literal]
82+
----
83+
SELECT proname, proconfig FROM pg_proc
84+
WHERE proname = 'take_sample' AND proconfig IS NOT NULL LIMIT 1;
85+
proname | proconfig
86+
-------------+-------------------------------------------------------------
87+
take_sample | {ivorysql.compatible_mode=pg,search_path=profile}
88+
----
89+
90+
== 使用流程
91+
92+
=== 创建样本
93+
[literal]
94+
----
95+
-- 第一次采样
96+
SELECT * FROM profile.take_sample();
97+
server | result | elapsed
98+
--------+--------+-------------
99+
local | OK | 00:00:01.34
100+
101+
-- ……业务负载运行一段时间后，再次采样
102+
SELECT * FROM profile.take_sample();
103+
----
104+
105+
生产环境通常用定时任务周期采样（如 30 分钟一次），可配合 pg_cron 或外部 crontab：
106+
[literal]
107+
----
108+
*/30 * * * * psql -c 'SELECT profile.take_sample()' >/dev/null
109+
----
110+
111+
=== 查看样本
112+
[literal]
113+
----
114+
SELECT sample, sample_time, sizes_collected FROM profile.show_samples();
115+
sample | sample_time | sizes_collected
116+
--------+------------------------+-----------------
117+
1 | 2026-06-12 09:00:00+00 | t
118+
2 | 2026-06-12 09:30:00+00 | t
119+
----
120+
121+
=== 生成报告
122+
[literal]
123+
----
124+
-- 生成样本 1 到样本 2 之间的负载报告（HTML 文本）
125+
\o report_1_2.html
126+
SELECT profile.get_report(1, 2);
127+
\o
128+
----
129+
130+
以上函数在 Oracle 模式会话（Oracle 端口/1521）中调用方式与结果完全一致。
131+
132+
== 注意事项
133+
134+
=== 适配说明
135+
IvorySQL 在 PG 模式下可直接安装使用 pg_profile 扩展，但在 Oracle 兼容模式下需要在编译时为 pg_profile 的 control.tpl 文件增加 `pg_dialect` 配置项，以启用 PG 语法解析器，避免安装失败。
136+
137+
=== 适配边界
138+
`pg_dialect` 适配机制保护的是*扩展自身的代码*；调用方会话中书写的 SQL 仍按会话方言解析。在 Oracle 模式会话中调用 pg_profile 时，语句里用户自己的表达式需符合 Oracle 模式语法，例如：
139+
[literal]
140+
----
141+
-- Oracle 会话中：PG 风格 interval 字面量会在会话解析期报错
142+
SELECT profile.set_server_size_sampling('local', current_time - interval '10 minute', ...); -- 错误
143+
144+
-- 应使用会话方言可接受的写法，或在 PG 模式会话中执行管理操作
145+
----

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
3535
|*21*| xref:master/ecosystem_components/pg_show_plans.adoc[pg_show_plans] | 2.1 | Displays execution plans of all currently running SQL statements, supporting TEXT, JSON, and YAML output formats | Query performance diagnosis, real-time execution plan monitoring, slow query analysis
3636
|*22*| xref:master/ecosystem_components/pg_bulkload.adoc[pg_bulkload] | 3.1.23 | Provides high-speed data loading tool for IvorySQL, which directly imports data into tables bypassing PostgreSQL shared buffers | initial loading of massive data, historical data archiving and cross-database migration
3737
|*23*| xref:master/ecosystem_components/pg_bigm.adoc[pg_bigm] | 1.2 | Equips IvorySQL with bigram full-text search capability, supporting Chinese, Japanese and Korean texts to implement fuzzy retrieval and similarity query efficiently | text search for articles, commodities and addresses in CJK languages
38+
|*24*| xref:master/ecosystem_components/pg_profile.adoc[pg_profile] | 4.11 | Collects statistics on resource-intensive database activities and generates historic workload reports based on delta analysis between two sample points, helping identify performance bottlenecks | Database performance analysis
3839
|====
3940

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

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

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
5+
= pg_profile
6+
7+
== Overview
8+
pg_profile is an extension tool for PostgreSQL database performance analysis. It is mainly used to collect resource-intensive activities in a target database, helping users gain in-depth insight into database runtime status, identify performance bottlenecks, and perform optimization. Its report is essentially a "delta analysis between two sample points", deriving the incremental load within the sampling interval, with sample point sequence numbers starting from 1.
9+
10+
pg_profile hard-depends on two extensions: dblink and plpgsql (it is written entirely in SQL and PL/pgSQL and requires no external libraries or software). Additionally, it is recommended to install the pg_stat_statements extension to obtain SQL statement-level statistics in the reports. The version of pg_profile is strongly tied to the version of PostgreSQL, currently supporting up to PG 18. For the specific version support, please refer to the README in the official pg_profile github repository.
11+
12+
Both the PG mode and Oracle compatibility mode of IvorySQL have been adapted for pg_profile. Note that in Oracle compatibility mode, before compiling pg_profile, you need to manually modify the control.tpl file in the extension source code to add a configuration item `pg_dialect = true`, otherwise the installation will fail.
13+
14+
Project address: <https://github.com/zubkov-andrei/pg_profile>
15+
16+
License: PostgreSQL License
17+
18+
== Installation and Enabling
19+
20+
=== Source Code Compilation
21+
To install pg_profile in IvorySQL's Oracle compatibility mode, you need to first modify the control.tpl file of pg_profile to add the `pg_dialect` configuration item:
22+
[literal]
23+
----
24+
# pg_profile/control.tpl
25+
pg_dialect = true
26+
----
27+
28+
Perform source code compilation and installation:
29+
[literal]
30+
----
31+
# Build and install pg_profile and its dependent extensions
32+
make -C contrib/dblink install
33+
make -C contrib/pg_stat_statements install
34+
make -C contrib/pg_profile install
35+
----
36+
37+
The installation artifacts are `pg_profile.control` and `pg_profile--4.11.sql`. In IvorySQL's Oracle compatibility mode, you can verify that the generated `pg_profile.control` file carries the `pg_dialect` declaration:
38+
[literal]
39+
----
40+
default_version = '4.11'
41+
requires = 'dblink,plpgsql'
42+
superuser = false
43+
44+
pg_dialect = true
45+
----
46+
47+
=== Modify Configuration
48+
The pg_stat_statements that pg_profile depends on must be loaded at server startup via `shared_preload_libraries`.
49+
50+
Edit `ivorysql.conf` and append `pg_stat_statements` to the end of the `shared_preload_libraries` configuration item:
51+
[literal]
52+
----
53+
# ivorysql.conf
54+
shared_preload_libraries = 'liboracle_parser, ivorysql_ora, pg_stat_statements'
55+
----
56+
57+
=== Restart the Service
58+
[literal]
59+
----
60+
pg_ctl -D $PGDATA restart
61+
----
62+
63+
=== Install the Extension
64+
The commands are identical in both PG mode and Oracle mode sessions:
65+
[literal]
66+
----
67+
CREATE SCHEMA profile;
68+
CREATE SCHEMA dblink;
69+
CREATE SCHEMA statements;
70+
CREATE EXTENSION dblink SCHEMA dblink;
71+
CREATE EXTENSION pg_stat_statements SCHEMA statements;
72+
CREATE EXTENSION pg_profile SCHEMA profile;
73+
74+
SELECT extname, extversion FROM pg_extension WHERE extname = 'pg_profile';
75+
extname | extversion
76+
------------+------------
77+
pg_profile | 4.11
78+
----
79+
80+
In Oracle compatibility mode, you can run the following query to confirm that the extension functions of pg_profile have been pinned to the PG syntax parser:
81+
[literal]
82+
----
83+
SELECT proname, proconfig FROM pg_proc
84+
WHERE proname = 'take_sample' AND proconfig IS NOT NULL LIMIT 1;
85+
proname | proconfig
86+
-------------+-------------------------------------------------------------
87+
take_sample | {ivorysql.compatible_mode=pg,search_path=profile}
88+
----
89+
90+
== Usage Workflow
91+
92+
=== Create Samples
93+
[literal]
94+
----
95+
-- First sampling
96+
SELECT * FROM profile.take_sample();
97+
server | result | elapsed
98+
--------+--------+-------------
99+
local | OK | 00:00:01.34
100+
101+
-- ...after the business workload runs for a while, sample again
102+
SELECT * FROM profile.take_sample();
103+
----
104+
105+
In production environments, periodic sampling via scheduled tasks is typically used (e.g., once every 30 minutes), which can be combined with pg_cron or an external crontab:
106+
[literal]
107+
----
108+
*/30 * * * * psql -c 'SELECT profile.take_sample()' >/dev/null
109+
----
110+
111+
=== View Samples
112+
[literal]
113+
----
114+
SELECT sample, sample_time, sizes_collected FROM profile.show_samples();
115+
sample | sample_time | sizes_collected
116+
--------+------------------------+-----------------
117+
1 | 2026-06-12 09:00:00+00 | t
118+
2 | 2026-06-12 09:30:00+00 | t
119+
----
120+
121+
=== Generate Reports
122+
[literal]
123+
----
124+
-- Generate the workload report between sample 1 and sample 2 (HTML text)
125+
\o report_1_2.html
126+
SELECT profile.get_report(1, 2);
127+
\o
128+
----
129+
130+
The above functions are invoked and produce identical results in an Oracle mode session (Oracle port/1521).
131+
132+
== Notes
133+
134+
=== Adaptation Description
135+
IvorySQL can directly install and use the pg_profile extension in PG mode. However, in Oracle compatibility mode, you need to add the `pg_dialect` configuration item to the control.tpl file of pg_profile at compile time to enable the PG syntax parser and avoid installation failure.
136+
137+
=== Adaptation Boundary
138+
The `pg_dialect` adaptation mechanism protects *the extension's own code*; the SQL written in the caller's session is still parsed according to the session dialect. When calling pg_profile in an Oracle mode session, the user's own expressions in the statements must conform to Oracle mode syntax, for example:
139+
[literal]
140+
----
141+
-- In an Oracle session: PG-style interval literals will cause an error during session parsing
142+
SELECT profile.set_server_size_sampling('local', current_time - interval '10 minute', ...); -- ERROR
143+
144+
-- Use a syntax acceptable to the session dialect, or perform management operations in a PG mode session
145+
----

0 commit comments

Comments
 (0)