Skip to content

Commit 969835a

Browse files
messere1messere1
committed
docs: add timescaledb toolkit adaptation guide
Rebased onto the current master; includes the review-comment fixes (normalized compatible_mode statement spacing) from the previous revision of this branch.
1 parent 4c54d8e commit 969835a

6 files changed

Lines changed: 218 additions & 0 deletions

File tree

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@
7878
*** xref:master/ecosystem_components/set_user.adoc[set_user]
7979
*** xref:master/ecosystem_components/pg_jieba.adoc[pg_jieba]
8080
*** xref:master/ecosystem_components/pg_track_settings.adoc[pg_track_settings]
81+
*** xref:master/ecosystem_components/timescaledb_toolkit.adoc[timescaledb_toolkit]
8182
* 监控运维
8283
** xref:master/getting-started/daily_monitoring.adoc[日常监控]
8384
** 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
@@ -43,6 +43,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
4343
| 30 | xref:master/ecosystem_components/set_user.adoc[set_user] | REL4_2_0 | PostgreSQL 安全审计扩展，可控角色切换，支持白名单、强制审计、拦截高危操作 | 可控角色切换、权限管理、审计日志
4444
| 31 | xref:master/ecosystem_components/pg_jieba.adoc[pg_jieba] | master branch | 中文分词扩展，能够将连续的中文文本切分成有意义的词语序列，为中文全文搜索提供基础支持 | 全文搜索、自然语言处理
4545
| 32 | xref:master/ecosystem_components/pg_track_settings.adoc[pg_track_settings] | 2.1.2 | PostgreSQL 配置跟踪扩展，记录配置变更历史 | 配置审计、变更追踪
46+
| 33 | xref:master/ecosystem_components/timescaledb_toolkit.adoc[timescaledb_toolkit] | 1.26.0 | 提供统计分析和时间序列聚合函数 | 可观测性、传感器分析、近似分析
4647
|====
4748

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

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

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= timescaledb_toolkit
5+
6+
== 概述
7+
8+
TimescaleDB Toolkit 为 PostgreSQL 提供统计分析、近似百分位数、近似去重计数、计数器和时间加权计算等聚合函数。Toolkit 也可运行在普通 PostgreSQL 兼容数据库上，本文示例不强制依赖 TimescaleDB。
9+
10+
本文在 x86_64 Linux 上使用 IvorySQL 5.4（PostgreSQL 18.4）、TimescaleDB Toolkit 1.26.0、Rust 1.98.1 和 `cargo-pgrx` 0.18.1 完成验证。Toolkit Rust 工作区测试全部通过，发布版扩展无需修改源码即可编译，代表性超函数在 PostgreSQL 和 Oracle 兼容会话中均通过验证。
11+
12+
== 准备环境
13+
14+
安装 C 编译工具链、Rust，以及与运行扩展的 IvorySQL 实例完全匹配的开发文件。Toolkit 1.26.0 要求 Rust 1.96 或更高版本。
15+
16+
[source,bash]
17+
----
18+
cargo install cargo-pgrx --version 0.18.1 --locked
19+
cargo pgrx init --pg18 /path-to/ivorysql/bin/pg_config
20+
----
21+
22+
== 编译安装
23+
24+
[source,bash]
25+
----
26+
git clone --branch 1.26.0 --depth 1 \
27+
https://github.com/timescale/timescaledb-toolkit.git
28+
cd timescaledb-toolkit
29+
30+
./tools/build \
31+
-pg18 \
32+
-pgconfig /path-to/ivorysql/bin/pg_config \
33+
-profile release \
34+
install
35+
----
36+
37+
部署前运行上游测试：
38+
39+
[source,bash]
40+
----
41+
cargo test --workspace --exclude timescaledb_toolkit
42+
----
43+
44+
== 创建扩展
45+
46+
通过 IvorySQL PostgreSQL 兼容端口连接，并在每个目标数据库中创建扩展：
47+
48+
[source,sql]
49+
----
50+
CREATE EXTENSION timescaledb_toolkit;
51+
SELECT extversion
52+
FROM pg_extension
53+
WHERE extname = 'timescaledb_toolkit';
54+
----
55+
56+
== 功能验证
57+
58+
[source,sql]
59+
----
60+
CREATE TABLE metrics (
61+
ts timestamptz NOT NULL,
62+
device text NOT NULL,
63+
value double precision NOT NULL
64+
);
65+
66+
INSERT INTO metrics VALUES
67+
('2026-01-01 00:00:00+00', 'sensor-a', 10),
68+
('2026-01-01 00:01:00+00', 'sensor-a', 20),
69+
('2026-01-01 00:02:00+00', 'sensor-b', 30),
70+
('2026-01-01 00:03:00+00', 'sensor-c', 40);
71+
72+
SELECT round(average(stats_agg(value))::numeric, 2) AS average_value,
73+
round(approx_percentile(0.5, percentile_agg(value))::numeric, 2)
74+
AS approximate_median
75+
FROM metrics;
76+
77+
SELECT distinct_count(hyperloglog(32, device)) AS approximate_devices
78+
FROM metrics;
79+
80+
SELECT round(delta(counter_agg(ts, value))::numeric, 2) AS counter_delta,
81+
round(average(time_weight('Linear', ts, value))::numeric, 2)
82+
AS time_weighted_average
83+
FROM metrics;
84+
----
85+
86+
验证结果分别为：平均值 `25.00`、近似中位数 `29.99`、设备数 3、计数器增量 `30.00`、时间加权平均值 `25.00`。
87+
88+
== Oracle 兼容模式
89+
90+
通过 PostgreSQL 兼容端口创建扩展后，可在 Oracle 兼容会话中调用已验证的函数：
91+
92+
[source,sql]
93+
----
94+
SET ivorysql.compatible_mode=oracle;
95+
SELECT 1 FROM dual;
96+
97+
SELECT round(average(stats_agg(value))::numeric, 2) AS oracle_average,
98+
distinct_count(hyperloglog(32, device)) AS oracle_devices
99+
FROM metrics;
100+
----
101+
102+
[IMPORTANT]
103+
====
104+
在 IvorySQL 5.4 中，直接通过 Oracle 兼容连接执行 `CREATE EXTENSION timescaledb_toolkit` 会失败，因为上游安装脚本使用 PostgreSQL 语法。请先通过 PostgreSQL 兼容端口创建扩展。该限制不影响切换到 Oracle 兼容模式后调用本文验证的 Toolkit 函数。
105+
====
106+
107+
Toolkit 本身不提供 hypertable 或后台任务；如需这些功能，应另行安装 TimescaleDB。完整函数说明请参阅 https://github.com/timescale/timescaledb-toolkit[上游项目]。

‎EN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@
7878
*** xref:master/ecosystem_components/set_user.adoc[set_user]
7979
*** xref:master/ecosystem_components/pg_jieba.adoc[pg_jieba]
8080
*** xref:master/ecosystem_components/pg_track_settings.adoc[pg_track_settings]
81+
*** xref:master/ecosystem_components/timescaledb_toolkit.adoc[timescaledb_toolkit]
8182
* Monitor and O&M
8283
** xref:master/getting-started/daily_monitoring.adoc[Monitoring]
8384
** 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
@@ -44,6 +44,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
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
4545
|*31*| xref:master/ecosystem_components/pg_jieba.adoc[pg_jieba] | master branch | Chinese word segmentation extension, which segments continuous Chinese text into meaningful word sequences, providing fundamental support for full-text search | Full-text search and natural language processing (NLP)
4646
|*32*| xref:master/ecosystem_components/pg_track_settings.adoc[pg_track_settings] | 2.1.2 | PostgreSQL configuration tracking extension that records configuration change history | Configuration auditing, change tracking
47+
|*33*| xref:master/ecosystem_components/timescaledb_toolkit.adoc[timescaledb_toolkit] | 1.26.0 | Provides statistical and time-series aggregate functions | Observability, sensor analytics, approximate analytics
4748
|====
4849

4950
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/timescaledb_toolkit.adoc‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= timescaledb_toolkit
5+
6+
== Overview
7+
8+
TimescaleDB Toolkit provides PostgreSQL aggregate functions for statistical analysis, approximate percentiles, distinct counting, counters, and time-weighted calculations. Toolkit can run on plain PostgreSQL-compatible databases; TimescaleDB is optional for the examples in this guide.
9+
10+
This guide was validated on x86_64 Linux with IvorySQL 5.4 (PostgreSQL 18.4), TimescaleDB Toolkit 1.26.0, Rust 1.98.1, and `cargo-pgrx` 0.18.1. The Toolkit Rust workspace tests passed, the release extension built without source changes, and representative hyperfunctions passed in PostgreSQL and Oracle-compatible sessions.
11+
12+
== Prerequisites
13+
14+
Install the C build toolchain, Rust, and the development files for the same IvorySQL installation that will load the extension. Toolkit 1.26.0 requires Rust 1.96 or later.
15+
16+
[source,bash]
17+
----
18+
cargo install cargo-pgrx --version 0.18.1 --locked
19+
cargo pgrx init --pg18 /path-to/ivorysql/bin/pg_config
20+
----
21+
22+
== Build and install
23+
24+
[source,bash]
25+
----
26+
git clone --branch 1.26.0 --depth 1 \
27+
https://github.com/timescale/timescaledb-toolkit.git
28+
cd timescaledb-toolkit
29+
30+
./tools/build \
31+
-pg18 \
32+
-pgconfig /path-to/ivorysql/bin/pg_config \
33+
-profile release \
34+
install
35+
----
36+
37+
Run the upstream tests before deployment:
38+
39+
[source,bash]
40+
----
41+
cargo test --workspace --exclude timescaledb_toolkit
42+
----
43+
44+
== Create the extension
45+
46+
Connect through the IvorySQL PostgreSQL-compatible port and create the extension in each target database:
47+
48+
[source,sql]
49+
----
50+
CREATE EXTENSION timescaledb_toolkit;
51+
SELECT extversion
52+
FROM pg_extension
53+
WHERE extname = 'timescaledb_toolkit';
54+
----
55+
56+
== Functional validation
57+
58+
[source,sql]
59+
----
60+
CREATE TABLE metrics (
61+
ts timestamptz NOT NULL,
62+
device text NOT NULL,
63+
value double precision NOT NULL
64+
);
65+
66+
INSERT INTO metrics VALUES
67+
('2026-01-01 00:00:00+00', 'sensor-a', 10),
68+
('2026-01-01 00:01:00+00', 'sensor-a', 20),
69+
('2026-01-01 00:02:00+00', 'sensor-b', 30),
70+
('2026-01-01 00:03:00+00', 'sensor-c', 40);
71+
72+
SELECT round(average(stats_agg(value))::numeric, 2) AS average_value,
73+
round(approx_percentile(0.5, percentile_agg(value))::numeric, 2)
74+
AS approximate_median
75+
FROM metrics;
76+
77+
SELECT distinct_count(hyperloglog(32, device)) AS approximate_devices
78+
FROM metrics;
79+
80+
SELECT round(delta(counter_agg(ts, value))::numeric, 2) AS counter_delta,
81+
round(average(time_weight('Linear', ts, value))::numeric, 2)
82+
AS time_weighted_average
83+
FROM metrics;
84+
----
85+
86+
The validated results are an average of `25.00`, an approximate median of `29.99`, three distinct devices, a counter delta of `30.00`, and a time-weighted average of `25.00`.
87+
88+
== Oracle-compatible mode
89+
90+
After creating the extension through the PostgreSQL-compatible port, the tested functions can be used in an Oracle-compatible session:
91+
92+
[source,sql]
93+
----
94+
SET ivorysql.compatible_mode=oracle;
95+
SELECT 1 FROM dual;
96+
97+
SELECT round(average(stats_agg(value))::numeric, 2) AS oracle_average,
98+
distinct_count(hyperloglog(32, device)) AS oracle_devices
99+
FROM metrics;
100+
----
101+
102+
[IMPORTANT]
103+
====
104+
With IvorySQL 5.4, running `CREATE EXTENSION timescaledb_toolkit` directly through an Oracle-compatible connection fails because the upstream installation script uses PostgreSQL syntax. Create the extension through the PostgreSQL-compatible port first. This limitation does not prevent the validated Toolkit functions from being called after switching a session to Oracle-compatible mode.
105+
====
106+
107+
Toolkit does not provide hypertables or background jobs. Install TimescaleDB separately if those features are required. See https://github.com/timescale/timescaledb-toolkit[the upstream project] for the complete function reference.

0 commit comments

Comments
 (0)