Skip to content

Commit 6c21504

Browse files
messere1messere1
committed
docs: add PoWA adaptation guide
1 parent ae32340 commit 6c21504

6 files changed

Lines changed: 204 additions & 0 deletions

File tree

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
*** xref:master/ecosystem_components/zhparser.adoc[zhparser]
7777
*** xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest]
7878
*** xref:master/ecosystem_components/set_user.adoc[set_user]
79+
*** xref:master/ecosystem_components/powa.adoc[PoWA]
7980
* 监控运维
8081
** xref:master/getting-started/daily_monitoring.adoc[日常监控]
8182
** 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
@@ -41,6 +41,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
4141
| 28 | xref:master/ecosystem_components/zhparser.adoc[zhparser] | master branch | 用于中文全文搜索的PostgreSQL插件，基于SCWS（即：简易中文分词系统）实现了一个中文解析器 | 搜索引擎、关键字提取
4242
| 29 | xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest] | 2.58.0 | 可靠的 PostgreSQL 备份和恢复解决方案 | 容灾备份、大库备份、异地/多层容灾
4343
| 30 | xref:master/ecosystem_components/set_user.adoc[set_user] | REL4_2_0 | PostgreSQL 安全审计扩展，可控角色切换，支持白名单、强制审计、拦截高危操作 | 可控角色切换、权限管理、审计日志
44+
| 31 | xref:master/ecosystem_components/powa.adoc[PoWA] | 5.3.0 | 采集并可视化数据库工作负载统计 | 性能监控、负载分析、查询调优
4445
|====
4546

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

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

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= PoWA
5+
6+
== 概述
7+
8+
PoWA（PostgreSQL Workload Analyzer）用于采集数据库工作负载统计，并通过 Web 界面展示。完整部署可以包含：
9+
10+
* `powa-archivist`：在数据库中存储和聚合指标的扩展；
11+
* `powa-web`：可视化界面；
12+
* `powa-collector`：从多个远程服务器采集指标的可选守护进程。
13+
14+
`pg_stat_statements` 是必需的主要数据源，其他统计扩展均为可选项。
15+
16+
本文在 x86_64 Linux 上使用 IvorySQL 5.4（PostgreSQL 18.4）和 PoWA Archivist 5.3.0 完成验证。扩展无需修改源码即可编译，8 项上游 PostgreSQL 回归测试全部通过。
17+
18+
== 选择部署模式
19+
20+
*本地模式*由 PoWA 后台工作进程在被监控的 IvorySQL 实例中采集并存储指标，适合快速评估，但采集、存储和可视化查询都会增加该实例的负载。
21+
22+
*远程模式*由 `powa-collector` 从被监控实例读取统计信息并写入专用仓库。生产环境推荐该架构，因为它可把存储和可视化开销移出业务数据库，并支持监控只读备库。
23+
24+
== 编译 PoWA Archivist
25+
26+
安装 IvorySQL 服务端开发文件，然后使用相匹配的 `pg_config` 编译：
27+
28+
[source,bash]
29+
----
30+
git clone --branch REL_5_3_0 --depth 1 \
31+
https://github.com/powa-team/powa-archivist.git
32+
cd powa-archivist
33+
34+
make PG_CONFIG=/path-to/ivorysql/bin/pg_config
35+
sudo make PG_CONFIG=/path-to/ivorysql/bin/pg_config install
36+
----
37+
38+
在测试实例上运行上游回归测试：
39+
40+
[source,bash]
41+
----
42+
PGUSER=ivorysql PGPORT=5432 \
43+
make PG_CONFIG=/path-to/ivorysql/bin/pg_config installcheck
44+
----
45+
46+
== 配置本地模式
47+
48+
在 `ivorysql.conf` 中保留已有 IvorySQL 库，并把 `pg_stat_statements` 和 `powa` 追加到 `shared_preload_libraries`：
49+
50+
[source,conf]
51+
----
52+
shared_preload_libraries = 'gb18030_2022, liboracle_parser, ivorysql_ora, pg_stat_statements, powa'
53+
track_io_timing = on
54+
----
55+
56+
重启 IvorySQL，创建专用数据库，并通过 PostgreSQL 兼容端口安装依赖扩展：
57+
58+
[source,bash]
59+
----
60+
pg_ctl restart -D /path-to/data
61+
createdb -p 5432 powa
62+
psql -p 5432 -d powa
63+
----
64+
65+
[source,sql]
66+
----
67+
CREATE EXTENSION pg_stat_statements;
68+
CREATE EXTENSION btree_gist;
69+
CREATE EXTENSION powa;
70+
----
71+
72+
生成少量负载并确认快照捕获了语句：
73+
74+
[source,sql]
75+
----
76+
SELECT sum(i) FROM generate_series(1, 100) AS g(i);
77+
SELECT powa_take_snapshot();
78+
79+
SELECT count(*) > 0 AS captured_statements
80+
FROM powa_statements_history_current;
81+
----
82+
83+
安装并配置 `powa-web`，使用指向 `powa` 数据库的 PostgreSQL DSN 查看仪表盘。生产环境应把 Web 服务放在启用身份认证和 TLS 的反向代理之后。
84+
85+
== 远程模式
86+
87+
生产环境或需要监控多个实例时，应在专用仓库中安装 PoWA Archivist 并运行 `powa-collector`。每个被监控的 IvorySQL 实例仍需加载并创建 `pg_stat_statements`。使用 PoWA 远程服务器 API 注册实例，再为 collector 配置仓库 DSN。
88+
89+
不要在 `powa_servers` 中保存明文密码。优先使用证书或受保护的密码文件等 libpq 认证方式；条件允许时，使用具有 `pg_read_all_stats` 权限的监控角色而不是超级用户。
90+
91+
== Oracle 兼容模式
92+
93+
[IMPORTANT]
94+
====
95+
PoWA 的安装和采集链路应使用 PostgreSQL 兼容端口。在 IvorySQL 5.4 中，通过 Oracle 兼容端口直接创建依赖扩展会失败，因为上游安装脚本使用 PostgreSQL 语法；在交互会话切换到 Oracle 模式后调用 `powa_take_snapshot()` 也可能遇到标识符大小写折叠差异。这些限制不影响 PostgreSQL 模式后台采集，也不影响 PoWA Web 通过 PostgreSQL 端口连接。
96+
====
97+
98+
Oracle 兼容会话仍可在需要时使用带引号的 schema 和对象名查询工作负载表，但管理配置和快照操作应保持在 PostgreSQL 模式。
99+
100+
生产部署前请阅读 https://powa.readthedocs.io/en/latest/architecture.html[PoWA 架构文档]中的本地与远程方案，以及 https://powa.readthedocs.io/en/latest/security.html[PoWA 安全指南]。

‎EN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
*** xref:master/ecosystem_components/zhparser_en.adoc[zhparser]
7777
*** xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest]
7878
*** xref:master/ecosystem_components/set_user.adoc[set_user]
79+
*** xref:master/ecosystem_components/powa.adoc[PoWA]
7980
* Monitor and O&M
8081
** xref:master/getting-started/daily_monitoring.adoc[Monitoring]
8182
** 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
@@ -42,6 +42,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
4242
|*28*| xref:master/ecosystem_components/zhparser_en.adoc[zhparser] | master branch | PostgreSQL extension for full-text search of Chinese language (Mandarin Chinese). It implements a Chinese language parser base on the | Search engine、keyword extraction
4343
|*29*| xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest] | 2.58.0 | pgBackRest is a reliable backup and restore solution for PostgreSQL that seamlessly scales up to the largest databases and workloads | Disaster recovery backup, large database backup, off-site/multi-tier disaster recovery
4444
| *30* | xref:master/ecosystem_components/set_user.adoc[set_user] | REL4_2_0 | PostgreSQL security auditing extension with controlled role switching, supporting allowlists, enforced auditing, and blocking of high-risk operations | Controlled role switching, privilege management, audit logging
45+
| *31* | xref:master/ecosystem_components/powa.adoc[PoWA] | 5.3.0 | Collects and visualizes database workload statistics | Performance monitoring, workload analysis, query tuning
4546
|====
4647

4748
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/powa.adoc‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= PoWA
5+
6+
== Overview
7+
8+
PoWA (PostgreSQL Workload Analyzer) collects workload statistics and presents them through a web interface. A complete deployment can contain:
9+
10+
* `powa-archivist`, the database extension that stores and aggregates metrics;
11+
* `powa-web`, the visualization interface;
12+
* `powa-collector`, the optional daemon used to collect multiple remote servers.
13+
14+
`pg_stat_statements` is the mandatory primary data source. Other statistics extensions are optional.
15+
16+
This guide was validated on x86_64 Linux with IvorySQL 5.4 (PostgreSQL 18.4) and PoWA Archivist 5.3.0. The extension built without source changes, and all eight upstream PostgreSQL regression tests passed.
17+
18+
== Choose a deployment mode
19+
20+
In *local mode*, PoWA's background worker collects and stores metrics in the monitored IvorySQL instance. This is simple for evaluation, but collection, storage, and visualization queries add load to that instance.
21+
22+
In *remote mode*, `powa-collector` reads statistics from monitored instances and writes them to a dedicated repository. This is the recommended production architecture because it moves storage and visualization overhead away from monitored databases and can monitor read-only standbys.
23+
24+
== Build PoWA Archivist
25+
26+
Install the IvorySQL server development files, then build against the matching `pg_config`:
27+
28+
[source,bash]
29+
----
30+
git clone --branch REL_5_3_0 --depth 1 \
31+
https://github.com/powa-team/powa-archivist.git
32+
cd powa-archivist
33+
34+
make PG_CONFIG=/path-to/ivorysql/bin/pg_config
35+
sudo make PG_CONFIG=/path-to/ivorysql/bin/pg_config install
36+
----
37+
38+
Run the upstream regression suite against a test instance:
39+
40+
[source,bash]
41+
----
42+
PGUSER=ivorysql PGPORT=5432 \
43+
make PG_CONFIG=/path-to/ivorysql/bin/pg_config installcheck
44+
----
45+
46+
== Configure local mode
47+
48+
Append `pg_stat_statements` and `powa` to the existing `shared_preload_libraries` value in `ivorysql.conf`. Preserve the IvorySQL libraries already configured:
49+
50+
[source,conf]
51+
----
52+
shared_preload_libraries = 'gb18030_2022, liboracle_parser, ivorysql_ora, pg_stat_statements, powa'
53+
track_io_timing = on
54+
----
55+
56+
Restart IvorySQL, create a dedicated database, and install the required extensions through the PostgreSQL-compatible port:
57+
58+
[source,bash]
59+
----
60+
pg_ctl restart -D /path-to/data
61+
createdb -p 5432 powa
62+
psql -p 5432 -d powa
63+
----
64+
65+
[source,sql]
66+
----
67+
CREATE EXTENSION pg_stat_statements;
68+
CREATE EXTENSION btree_gist;
69+
CREATE EXTENSION powa;
70+
----
71+
72+
Generate a small workload and confirm that a snapshot captures statements:
73+
74+
[source,sql]
75+
----
76+
SELECT sum(i) FROM generate_series(1, 100) AS g(i);
77+
SELECT powa_take_snapshot();
78+
79+
SELECT count(*) > 0 AS captured_statements
80+
FROM powa_statements_history_current;
81+
----
82+
83+
Install and configure `powa-web` with a PostgreSQL DSN pointing to the `powa` database to view dashboards. Place the web service behind an authenticated TLS reverse proxy in production.
84+
85+
== Remote mode
86+
87+
For production or multiple monitored instances, install PoWA Archivist in a dedicated repository and run `powa-collector`. Each monitored IvorySQL instance still needs `pg_stat_statements` loaded and created. Register monitored servers with PoWA's remote-server API, then configure the collector with the repository DSN.
88+
89+
Avoid storing plaintext passwords in `powa_servers`. Prefer a supported libpq authentication method such as certificates or a protected password file. Use a monitoring role with `pg_read_all_stats` instead of a superuser where possible.
90+
91+
== Oracle-compatible mode
92+
93+
[IMPORTANT]
94+
====
95+
Install and operate PoWA's collection path through the PostgreSQL-compatible port. On IvorySQL 5.4, creating the prerequisites directly through the Oracle-compatible port fails because their upstream installation scripts use PostgreSQL syntax. Calling `powa_take_snapshot()` after switching an interactive session to Oracle mode can also encounter identifier-folding differences. These limitations do not affect PostgreSQL-mode background collection or a PoWA Web connection using the PostgreSQL port.
96+
====
97+
98+
An Oracle-compatible session can still query workload tables with explicitly quoted schema and object names when required, but administrative setup and snapshot operations should remain in PostgreSQL mode.
99+
100+
See the https://powa.readthedocs.io/en/latest/architecture.html[PoWA architecture documentation] for local and remote designs, and the https://powa.readthedocs.io/en/latest/security.html[PoWA security guidance] before production deployment.

0 commit comments

Comments
 (0)