Skip to content

Commit 662fb19

Browse files
gaoxueyugaoxueyu
authored
Merge pull request #271 from hs-liuxh/master
Add ecosystem component: pg_profile & pg_repack
2 parents 6421676 + 7b34805 commit 662fb19

8 files changed

Lines changed: 429 additions & 2 deletions

File tree

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,10 @@
6565
*** xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan]
6666
*** xref:master/ecosystem_components/redis_fdw.adoc[redis_fdw]
6767
*** xref:master/ecosystem_components/pg_show_plans.adoc[pg_show_plans]
68+
*** xref:master/ecosystem_components/pg_bulkload.adoc[pg_bulkload]
69+
*** xref:master/ecosystem_components/pg_bigm.adoc[pg_bigm]
70+
*** xref:master/ecosystem_components/pg_profile.adoc[pg_profile]
71+
*** xref:master/ecosystem_components/pg_repack.adoc[pg_repack]
6872
*** xref:master/ecosystem_components/pgdog.adoc[PgDog]
6973
* 监控运维
7074
** xref:master/getting-started/daily_monitoring.adoc[日常监控]

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,9 @@ 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/pgdog.adoc[PgDog] | 0.1.45 | 专为 PostgreSQL 设计的高性能、开源集群中间件（代理工具），采用 Rust 语言编写 | 自动分片、连接池和负载均衡功能
37+
| 24 | xref:master/ecosystem_components/pg_profile.adoc[pg_profile] | 4.11 | 收集数据库资源密集型活动的统计，基于两次采样点的差量分析生成历史负载报告，帮助定位性能瓶颈 | 数据库性能分析
38+
| 25 | xref:master/ecosystem_components/pg_repack.adoc[pg_repack] | 1.5.3 | 在几乎不阻塞业务读写的情况下在线重整表和索引、消除存储膨胀，效果类似 VACUUM FULL | 表与索引在线重建、存储空间回收
39+
| 26 | xref:master/ecosystem_components/pgdog.adoc[PgDog] | 0.1.45 | 专为 PostgreSQL 设计的高性能、开源集群中间件（代理工具），采用 Rust 语言编写 | 自动分片、连接池和负载均衡功能
3840
|====
3941

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

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

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
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。
13+
14+
项目地址：<https://github.com/zubkov-andrei/pg_profile>
15+
16+
开源协议：PostgreSQL License
17+
18+
== 安装启用
19+
20+
=== 源码编译
21+
执行源码编译和安装：
22+
[literal]
23+
----
24+
# 构建并安装 pg_profile 及其依赖扩展
25+
make -C contrib/dblink install
26+
make -C contrib/pg_stat_statements install
27+
make -C contrib/pg_profile install
28+
----
29+
30+
安装产物为 `pg_profile.control` 与 `pg_profile--4.11.sql`。
31+
32+
=== 修改配置
33+
pg_profile 依赖的 pg_stat_statements 必须通过 `shared_preload_libraries` 在服务启动时加载。
34+
35+
编辑 `ivorysql.conf` ，在 `shared_preload_libraries` 配置项末尾追加 `pg_stat_statements`：
36+
[literal]
37+
----
38+
# ivorysql.conf
39+
shared_preload_libraries = 'liboracle_parser, ivorysql_ora, pg_stat_statements'
40+
----
41+
42+
=== 重启服务
43+
[literal]
44+
----
45+
pg_ctl -D $PGDATA restart
46+
----
47+
48+
=== 安装扩展
49+
PG 模式与 Oracle 模式会话下命令相同：
50+
[literal]
51+
----
52+
CREATE SCHEMA profile;
53+
CREATE SCHEMA dblink;
54+
CREATE SCHEMA statements;
55+
CREATE EXTENSION dblink SCHEMA dblink;
56+
CREATE EXTENSION pg_stat_statements SCHEMA statements;
57+
CREATE EXTENSION pg_profile SCHEMA profile;
58+
59+
SELECT extname, extversion FROM pg_extension WHERE extname = 'pg_profile';
60+
extname | extversion
61+
------------+------------
62+
pg_profile | 4.11
63+
----
64+
65+
== 使用流程
66+
67+
=== 创建样本
68+
[literal]
69+
----
70+
-- 第一次采样
71+
SELECT * FROM profile.take_sample();
72+
server | result | elapsed
73+
--------+--------+-------------
74+
local | OK | 00:00:01.34
75+
76+
-- ……业务负载运行一段时间后，再次采样
77+
SELECT * FROM profile.take_sample();
78+
----
79+
80+
生产环境通常用定时任务周期采样（如 30 分钟一次），可配合 pg_cron 或外部 crontab：
81+
[literal]
82+
----
83+
*/30 * * * * psql -c 'SELECT profile.take_sample()' >/dev/null
84+
----
85+
86+
=== 查看样本
87+
[literal]
88+
----
89+
SELECT sample, sample_time, sizes_collected FROM profile.show_samples();
90+
sample | sample_time | sizes_collected
91+
--------+------------------------+-----------------
92+
1 | 2026-06-12 09:00:00+00 | t
93+
2 | 2026-06-12 09:30:00+00 | t
94+
----
95+
96+
=== 生成报告
97+
[literal]
98+
----
99+
-- 生成样本 1 到样本 2 之间的负载报告（HTML 文本）
100+
\o report_1_2.html
101+
SELECT profile.get_report(1, 2);
102+
\o
103+
----
104+
105+
以上函数在 Oracle 模式会话（Oracle 端口/1521）中调用方式与结果完全一致。

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

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
5+
= pg_repack
6+
7+
== 概述
8+
pg_repack 是 PostgreSQL 的一个扩展，用于在线重整表和索引、消除存储膨胀。它能达到与 `VACUUM FULL` 类似的效果，回收空间，但几乎不阻塞业务读写。
9+
10+
IvorySQL 的 PG 模式和 Oracle 兼容模式都已经适配 pg_repack。
11+
12+
项目地址：<https://github.com/reorg/pg_repack>
13+
14+
官方文档：<https://reorg.github.io/pg_repack/>
15+
16+
开源协议：BSD-3-Clause License
17+
18+
== 原理
19+
VACUUM FULL 因没有"重写期间的并发变更捕获机制"，重写整表时全程持有 ACCESS EXCLUSIVE 锁，期间表不可读写，锁时长随表增大。pg_repack 通过"影子表 + 触发器 + 文件节点交换"把强锁压缩到首尾两个瞬间，从而支持在线重整。
20+
21+
=== 变更捕获与数据拷贝
22+
* 先在原表上安装行级触发器，把此后发生的 INSERT/UPDATE/DELETE 记入日志表（repack.log_<oid>）——这一步需短暂的 ACCESS EXCLUSIVE 锁以原子地装上触发器，装好即释放;
23+
24+
* 创建与原表结构相同的影子表（repack.table_<oid>），在一致性 MVCC 快照下把原表数据批量拷入;此阶段只持 SHARE UPDATE EXCLUSIVE，原表照常读写;
25+
26+
* 在影子表上重建索引，并回放日志，使影子表追平原表最新状态。
27+
28+
=== 交换与清理
29+
* 取得短暂的 ACCESS EXCLUSIVE 锁，回放剩余日志后，在系统目录层面交换原表与影子表的物理文件节点（relfilenode），表的 OID 保持不变——交换是瞬时的;
30+
31+
* 删除触发器、日志表，并删除影子表（此时它已指向旧堆，删除即回收旧物理文件）;最后对表执行 ANALYZE。
32+
33+
[NOTE]
34+
====
35+
使用前提：目标表必须有主键或非空唯一键；操作过程中约需要两倍表大小的临时磁盘空间。
36+
====
37+
38+
== 安装启用
39+
环境中已经安装了 IvorySQL5 及以上版本。pg_repack 由两部分组成：服务端扩展（`pg_repack.so` 与 SQL 脚本）和客户端命令行工具 `pg_repack`。
40+
41+
假设当前已安装 IvorySQL5，并且 pg_config 工具可用。
42+
43+
=== 源码安装
44+
拉取 pg_repack 源码：
45+
[literal]
46+
----
47+
git clone --branch ver_1.5.3 https://github.com/reorg/pg_repack.git
48+
----
49+
50+
执行编译和安装：
51+
[literal]
52+
----
53+
cd pg_repack
54+
make
55+
make install
56+
----
57+
58+
=== 创建扩展
59+
[literal]
60+
----
61+
[ivorysql@localhost ivorysql]$ psql
62+
psql (18.0)
63+
Type "help" for help.
64+
65+
ivorysql=# CREATE EXTENSION pg_repack;
66+
CREATE EXTENSION
67+
----
68+
69+
[NOTE]
70+
====
71+
`CREATE EXTENSION pg_repack` 需要超级用户执行；客户端工具 `pg_repack` 默认也要求以超级用户身份连接运行。
72+
====
73+
74+
== 使用流程
75+
pg_repack 通过命令行客户端驱动，连接参数与 psql 一致（`-h` 主机、`-p` 端口、`-U` 用户、`-d` 数据库，或使用 `PGHOST` / `PGPORT` / `PGUSER` 环境变量）。
76+
77+
=== 重整整个数据库中所有符合条件的表
78+
[literal]
79+
----
80+
pg_repack -d ivorysql
81+
----
82+
83+
=== 重整指定表
84+
推荐使用 schema.table 形式：
85+
[literal]
86+
----
87+
pg_repack -d ivorysql -t public.big_table
88+
----
89+
90+
=== 仅重建索引
91+
[literal]
92+
----
93+
pg_repack -d ivorysql -t big_table --only-indexes # 重建该表的全部索引
94+
pg_repack -d ivorysql -i public.big_table_idx # 重建单个索引
95+
----
96+
97+
=== 预演模式
98+
只显示将要执行的动作，不实际重整：
99+
[literal]
100+
----
101+
pg_repack -d ivorysql -t big_table --dry-run
102+
----

‎EN/modules/ROOT/nav.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,10 @@
6565
*** xref:master/ecosystem_components/pg_hint_plan.adoc[pg_hint_plan]
6666
*** xref:master/ecosystem_components/redis_fdw.adoc[redis_fdw]
6767
*** xref:master/ecosystem_components/pg_show_plans.adoc[pg_show_plans]
68+
*** xref:master/ecosystem_components/pg_bulkload.adoc[pg_bulkload]
69+
*** xref:master/ecosystem_components/pg_bigm.adoc[pg_bigm]
70+
*** xref:master/ecosystem_components/pg_profile.adoc[pg_profile]
71+
*** xref:master/ecosystem_components/pg_repack.adoc[pg_repack]
6872
*** xref:master/ecosystem_components/pgdog.adoc[PgDog]
6973
* Monitor and O&M
7074
** xref:master/getting-started/daily_monitoring.adoc[Monitoring]

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,9 @@ 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/pgdog.adoc[PgDog] | 0.1.45 | High-performance, open-source clustering middleware (proxy tool) designed specifically for PostgreSQL and written in Rust | Connection pooler, load balancer, distributed database.
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
39+
|*25*| xref:master/ecosystem_components/pg_repack.adoc[pg_repack] | 1.5.3 | Rebuilds tables and indexes online with minimal locking, eliminating storage bloat and achieving effects similar to VACUUM FULL | Online table and index rebuild, storage bloat reclamation
40+
|*26*| xref:master/ecosystem_components/pgdog.adoc[PgDog] | 0.1.45 | High-performance, open-source clustering middleware (proxy tool) designed specifically for PostgreSQL and written in Rust | Connection pooler, load balancer, distributed database.
3941
|====
4042

4143
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: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
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. 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.
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+
22+
Perform source code compilation and installation:
23+
[literal]
24+
----
25+
# Build and install pg_profile and its dependent extensions
26+
make -C contrib/dblink install
27+
make -C contrib/pg_stat_statements install
28+
make -C contrib/pg_profile install
29+
----
30+
31+
The installation artifacts are `pg_profile.control` and `pg_profile--4.11.sql`.
32+
33+
=== Modify Configuration
34+
The pg_stat_statements that pg_profile depends on must be loaded at server startup via `shared_preload_libraries`.
35+
36+
Edit `ivorysql.conf` and append `pg_stat_statements` to the end of the `shared_preload_libraries` configuration item:
37+
[literal]
38+
----
39+
# ivorysql.conf
40+
shared_preload_libraries = 'liboracle_parser, ivorysql_ora, pg_stat_statements'
41+
----
42+
43+
=== Restart the Service
44+
[literal]
45+
----
46+
pg_ctl -D $PGDATA restart
47+
----
48+
49+
=== Install the Extension
50+
The commands are identical in both PG mode and Oracle mode sessions:
51+
[literal]
52+
----
53+
CREATE SCHEMA profile;
54+
CREATE SCHEMA dblink;
55+
CREATE SCHEMA statements;
56+
CREATE EXTENSION dblink SCHEMA dblink;
57+
CREATE EXTENSION pg_stat_statements SCHEMA statements;
58+
CREATE EXTENSION pg_profile SCHEMA profile;
59+
60+
SELECT extname, extversion FROM pg_extension WHERE extname = 'pg_profile';
61+
extname | extversion
62+
------------+------------
63+
pg_profile | 4.11
64+
----
65+
66+
== Usage Workflow
67+
68+
=== Create Samples
69+
[literal]
70+
----
71+
-- First sampling
72+
SELECT * FROM profile.take_sample();
73+
server | result | elapsed
74+
--------+--------+-------------
75+
local | OK | 00:00:01.34
76+
77+
-- ...after the business workload runs for a while, sample again
78+
SELECT * FROM profile.take_sample();
79+
----
80+
81+
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:
82+
[literal]
83+
----
84+
*/30 * * * * psql -c 'SELECT profile.take_sample()' >/dev/null
85+
----
86+
87+
=== View Samples
88+
[literal]
89+
----
90+
SELECT sample, sample_time, sizes_collected FROM profile.show_samples();
91+
sample | sample_time | sizes_collected
92+
--------+------------------------+-----------------
93+
1 | 2026-06-12 09:00:00+00 | t
94+
2 | 2026-06-12 09:30:00+00 | t
95+
----
96+
97+
=== Generate Reports
98+
[literal]
99+
----
100+
-- Generate the workload report between sample 1 and sample 2 (HTML text)
101+
\o report_1_2.html
102+
SELECT profile.get_report(1, 2);
103+
\o
104+
----
105+
106+
The above functions are invoked and produce identical results in an Oracle mode session (Oracle port/1521).

0 commit comments

Comments
 (0)