Skip to content

Commit 95a776d

Browse files
gaoxueyugaoxueyu
authored
Merge pull request #181 from yuanyl630/addon
add document for 4 adapted extensions and overview part
2 parents 40dc36c + b9cad5e commit 95a776d

18 files changed

Lines changed: 725 additions & 42 deletions

File tree

‎CN/modules/ROOT/images/p31.png‎

79 KB
Loading

‎CN/modules/ROOT/images/p32.png‎

193 KB
Loading

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,12 @@
1313
*** xref:master/4.4.adoc[运维管理指南]
1414
*** xref:master/4.5.adoc[迁移指南]
1515
** IvorySQL生态
16-
*** xref:master/5.1.adoc[PostGIS]
16+
*** xref:master/5.0.adoc[概述]
1717
*** xref:master/5.2.adoc[pgvector]
18+
*** xref:master/5.3.adoc[pgddl(DDL Extractor)]
19+
*** xref:master/5.4.adoc[pg_cron]
20+
*** xref:master/5.5.adoc[pgsql-http]
21+
*** xref:master/5.6.adoc[plpgsql_check]
1822
** IvorySQL架构设计
1923
*** 查询处理
2024
**** xref:master/6.1.1.adoc[双parser]

‎CN/modules/ROOT/pages/master/5.0.adoc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
5+
[discrete]
6+
== IvorySQL生态插件适配列表
7+
8+
IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库，具备强大的扩展能力，支持丰富的生态系统插件。这些插件可以帮助用户在不同场景下增强数据库功能，包括地理信息处理、向量检索、全文搜索、数据定义提取和路径规划等。以下是当前 IvorySQL 官方兼容和支持的主要插件列表：
9+
10+
+
11+
12+
[cols="2,1,3,3"]
13+
|====
14+
|*插件名称*|*版本*|*功能描述*|*适用场景*
15+
| xref:master/5.2.adoc[pgvector] | 0.8.1 | 支持向量相似性搜索，可用于存储和检索高维向量数据| AI 应用、图像检索、推荐系统、语义搜索
16+
| xref:master/5.3.adoc[pgddl (DDL Extractor)] | 0.31 | 提取数据库中的 DDL（数据定义语言）语句，便于版本管理和迁移 | 数据库版本控制、CI/CD 集成、结构比对与同步
17+
| xref:master/5.4.adoc[pg_cron]​ | 1.6.0 | 提供数据库内部的定时任务调度功能，支持定期执行SQL语句 | 数据清理、定期统计、自动化维护任务
18+
| xref:master/5.5.adoc[pgsql-http]​ | 1.7.0 | 允许在SQL中发起HTTP请求，与外部Web服务进行交互 | 数据采集、API集成、微服务调用
19+
| xref:master/5.6.adoc[plpgsql_check] | 2.8 | 提供PL/pgSQL代码的静态分析功能，可在开发阶段发现潜在错误 | 存储过程开发、代码质量检查、调试优化
20+
|====
21+
22+
这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。
23+
24+
我们也将持续扩展和丰富 IvorySQL 的插件生态，欢迎社区开发者提交新的插件适配建议或代码贡献。如需了解更多每个插件的详细使用方法和最新兼容版本，请参阅各插件对应的文档章节。

‎CN/modules/ROOT/pages/master/5.2.adoc‎

Lines changed: 32 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -23,38 +23,46 @@ HNSW (Hierarchical Navigating Small World) 是一种基于图的索引算法，
2323
== 安装
2424
[TIP]
2525
====
26-
环境中已经安装了IvorySQL4.5及以上版本，安装路径为/usr/local/ivorysql/ivorysql-4
26+
环境中已经安装了IvorySQL5及以上版本，安装路径为/usr/local/ivorysql/ivorysql-5
2727
====
2828

2929
=== 源码安装
3030

3131
** 设置PG_CONFIG环境变量
32-
```
33-
export PG_CONFIG=/usr/local/ivorysql/ivorysql-4/bin/pg_config
34-
```
32+
+
33+
[literal]
34+
----
35+
export PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config
36+
----
3537

3638
** 拉取pg_vector源码
37-
```
39+
+
40+
[literal]
41+
----
3842
git clone --branch v0.8.1 https://github.com/pgvector/pgvector.git
39-
```
43+
----
4044

4145
** 安装 pgvector
42-
```
46+
+
47+
[literal]
48+
----
4349
cd pgvector
4450
4551
sudo --preserve-env=PG_CONFIG make
4652
sudo --preserve-env=PG_CONFIG make install
47-
```
53+
----
4854

4955
** 创建pgvector扩展
50-
```
51-
[ivorysql@localhost ivorysql-4]$ psql
52-
psql (17.5)
56+
+
57+
[literal]
58+
----
59+
[ivorysql@localhost ivorysql-5]$ psql
60+
psql (18.0)
5361
Type "help" for help.
5462
5563
ivorysql=# create extension vector;
5664
CREATE EXTENSION
57-
```
65+
----
5866
至此，pgvector扩展安装已完成。
5967
更多用例，请参考 https://github.com/pgvector/pgvector?tab=readme-ov-file#getting-started[pgvector文档]
6068

@@ -66,7 +74,8 @@ CREATE EXTENSION
6674

6775
=== 数据类型
6876

69-
```
77+
[literal]
78+
----
7079
ivorysql=# CREATE TABLE items5 (id bigserial PRIMARY KEY, name varchar2(20), num number(20), embedding bit(3));
7180
CREATE TABLE
7281
ivorysql=# INSERT INTO items5 (name, num, embedding) VALUES ('1st oracle data',0, '000'), ('2nd oracle data', 111, '111');
@@ -76,11 +85,12 @@ ivorysql=# SELECT * FROM items5 ORDER BY bit_count(embedding # '101') LIMIT 5;
7685
----+-----------------+-----+-----------
7786
2 | 2nd oracle data | 111 | 111
7887
1 | 1st oracle data | 0 | 000
79-
```
88+
----
8089

8190
=== 匿名块
8291

83-
```
92+
[literal]
93+
----
8494
ivorysql=# declare
8595
i vector(3) := '[1,2,3]';
8696
begin
@@ -89,10 +99,11 @@ end;
8999
ivorysql-# /
90100
NOTICE: [1,2,3]
91101
DO
92-
```
102+
----
93103

94104
=== 存储过程（PROCEDURE）
95-
```
105+
[literal]
106+
----
96107
ivorysql=# CREATE OR REPLACE PROCEDURE ora_procedure()
97108
AS
98109
p vector(3) := '[4,5,6]';
@@ -104,10 +115,11 @@ CREATE PROCEDURE
104115
ivorysql=# call ora_procedure();
105116
NOTICE: [4,5,6]
106117
CALL
107-
```
118+
----
108119

109120
==== 函数（FUNCTION）
110-
```
121+
[literal]
122+
----
111123
ivorysql=# CREATE OR REPLACE FUNCTION AddVector(a vector(3), b vector(3))
112124
RETURN vector(3)
113125
IS
@@ -121,4 +133,4 @@ ivorysql=# SELECT AddVector('[1,2,3]','[4,5,6]') FROM DUAL;
121133
----------------
122134
[5,7,9]
123135
(1 row)
124-
```
136+
----

‎CN/modules/ROOT/pages/master/5.3.adoc‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
5+
= pgddl (DDL Extractor)
6+
7+
== 概述
8+
pgddl 是一个专为 PostgreSQL 数据库设计的 SQL 函数扩展，它能够直接从数据库系统目录中生成清晰、格式化的 SQL DDL (数据定义语言) 脚本，例如 CREATE TABLE 或 ALTER FUNCTION。它解决了 PostgreSQL 原生缺乏类似 SHOW CREATE TABLE 命令的问题，让用户无需借助外部工具（如 pg_dump）即可在纯 SQL 环境中轻松获取对象的创建语句。
9+
10+
该扩展通过一组简单的 SQL 函数提供了一套完整的解决方案，其优势包括：仅需使用 SQL 查询即可操作、支持通过 WHERE 子句灵活筛选对象、并能智能处理对象之间的依赖关系，生成包含 Drop 和 Create 步骤的完整脚本。这使得它特别适用于数据库变更管理、升级脚本编写和结构审计等场景。
11+
12+
需要注意的是，ddlx 仍在发展中，可能尚未覆盖所有 PostgreSQL 对象类型和高级选项。生成的脚本建议始终在非生产环境中先行检查和测试，以确保其正确性与安全性。
13+
14+
== 安装
15+
IvorySQL的安装包里已经集成了pgddl插件，如果使用安装包安装的IvorySQL，通常不需要再手动安装pgddl即可使用。其它安装方式可以参考下面的源码安装步骤。
16+
17+
[TIP]
18+
源码安装环境为 Ubuntu 24.04(x86_64)，环境中已经安装了IvorySQL5及以上版本，安装路径为/usr/local/ivorysql/ivorysql-5
19+
20+
=== 源码安装
21+
从https://github.com/lacanoid/pgddl 下载pgddl v0.31代码。
22+
23+
[literal]
24+
----
25+
cd pgddl
26+
# 设置PG_CONFIG环境变量值为pg_config路径，eg：/usr/local/ivorysql/ivorysql-5/bin/pg_config
27+
make PG_CONFIG=/path/to/pg_config
28+
make PG_CONFIG=/path/to/pg_config install
29+
----
30+
31+
== 创建Extension并确认ddlx版本
32+
33+
psql 连接到数据库，执行如下命令：
34+
[literal]
35+
----
36+
ivorysql=# CREATE extension ddlx;
37+
CREATE EXTENSION
38+
39+
ivorysql=# SELECT * FROM pg_available_extensions WHERE name = 'ddlx';
40+
name | default_version | installed_version | comment
41+
------+-----------------+-------------------+-------------------------
42+
ddlx | 0.31 | 0.31 | DDL eXtractor functions
43+
(1 row)
44+
----
45+
46+
== 使用
47+
关于pgddl的使用，请参阅 https://github.com/lacanoid/pgddl[ddlx官方文档]

‎CN/modules/ROOT/pages/master/5.4.adoc‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
:imagesdir: ./_images
5+
6+
= pg_cron
7+
8+
== 概述
9+
在 PostgreSQL 中运行周期性任务，例如执行 VACUUM或删除旧数据，是一种常见需求。实现这一点的简单方法是配置 cron或其他外部守护进程，使其定期连接到数据库并运行命令。然而，随着数据库越来越多地作为托管服务或独立容器运行，配置和运行一个单独的守护进程通常变得不切实际。此外，很难让您的 cron任务感知故障转移，或者跨集群节点调度任务。
10+
11+
pg_cron 是 PostgreSQL 的开源定时任务扩展，允许直接在数据库内部设置 cron 风格的任务调度，用于自动化数据维护任务(清理，聚合), 数据库健康检查，执行存储过程和自定义函数等操作。它将cron任务存储在表中，周期性任务会随着 PostgreSQL 服务器自动进行故障转移。详情可以参见 https://github.com/citusdata/pg_cron[pg_cron文档]。
12+
13+
== 安装配置
14+
15+
[TIP]
16+
源码安装环境为 Ubuntu 24.04(x86_64)，环境中已经安装了IvorySQL5及以上版本，安装路径为/usr/local/ivorysql/ivorysql-5
17+
18+
=== 源码安装
19+
20+
[literal]
21+
----
22+
# 拉取pg_cron源码
23+
git clone https://github.com/citusdata/pg_cron.git
24+
cd pg_cron
25+
# 将pg_config的路径设置到PATH环境变量里，eg：
26+
export PATH=/usr/local/ivorysql/ivorysql-5/bin/:$PATH
27+
make
28+
make install
29+
----
30+
31+
=== 配置文件 (ivorysql.conf)
32+
33+
[literal]
34+
----
35+
# 共享预加载扩展
36+
shared_preload_libraries = 'pg_cron'
37+
38+
# 指定任务元数据存储库（默认当前库）
39+
cron.database_name = 'ivorysql'
40+
41+
# 允许的最大并发任务数
42+
cron.max_running_jobs = 5
43+
----
44+
45+
=== 重启服务
46+
47+
[literal]
48+
----
49+
pg_ctl restart -D ./data -l logfile
50+
----
51+
52+
=== 创建Extension并确认pg_cron版本
53+
54+
psql 连接到数据库，执行如下命令：
55+
[literal]
56+
----
57+
ivorysql=# CREATE extension pg_cron;
58+
CREATE EXTENSION
59+
60+
ivorysql=# SELECT * FROM pg_available_extensions WHERE name = 'pg_cron';
61+
name | default_version | installed_version | comment
62+
---------+-----------------+-------------------+---------------------------
63+
pg_cron | 1.6 | |Job scheduler for PostgreSQL
64+
(1 row)
65+
----
66+
67+
== 核心功能使用
68+
69+
=== 创建定时任务
70+
71+
[literal]
72+
----
73+
SELECT cron.schedule(
74+
'nightly-data-cleanup', -- 任务名称（唯一标识）
75+
'0 3 * * *', -- cron表达式（每天UTC 3:00）
76+
$$DELETE FROM logs
77+
WHERE created_at < now() - interval '30 days'$$ -- 执行SQL
78+
);
79+
----
80+
81+
cron表达式速查表：
82+
83+
|====
84+
|示例|含义
85+
|'0 * * * *'|每小时整点执行
86+
|'*/15 * * * *'|每15分钟执行
87+
|'0 9 * * 1-5'|工作日早9点执行
88+
|'0 1 1 * *'|每月1日凌晨1点执行
89+
|====
90+
91+
pg_cron还允许使用 '$'表示月份的最后一天。
92+
93+
=== 任务管理
94+
95+
[literal]
96+
----
97+
# 查看所有任务
98+
SELECT * FROM cron.job;
99+
----
100+
101+
image::p31.png[]
102+
103+
[literal]
104+
----
105+
# 查看任务执行历史
106+
SELECT * FROM cron.job_run_details ORDER BY start_time DESC LIMIT 10;
107+
----
108+
109+
image::p32.png[]
110+
111+
[literal]
112+
----
113+
# 删除任务
114+
SELECT cron.unschedule('nightly-data-cleanup');
115+
116+
# 暂停任务（更新状态）
117+
UPDATE cron.job SET active = false WHERE jobname = 'delete-job-run-details';
118+
----

‎CN/modules/ROOT/pages/master/5.5.adoc‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
2+
:sectnums:
3+
:sectnumlevels: 5
4+
5+
= pgsql-http
6+
7+
== 概述
8+
pgsql-http 是一个为 PostgreSQL 数据库设计的开源扩展，它允许用户直接在数据库内部发起 HTTP 请求，扮演了一个内置 Web 客户端的角色。该扩展的核心目的是打通数据库与外部 Web 服务之间的壁垒，使得通过简单的 SQL 函数调用即可与外部 Web 服务、API 端点进行交互，无需依赖外部应用程序或中间件。
9+
10+
借助此扩展，开发者可以在 SQL 查询、触发器或存储过程中直接获取网络数据（GET）、提交数据（POST/PUT）、更新（PATCH）或删除（DELETE）远程资源。它提供了丰富的功能，包括设置请求头、自动处理 URL 编码、发送 JSON 数据以及解析响应状态、头部和内容，极大简化了将外部数据集成到数据库操作中的流程。
11+
12+
其典型应用场景包括：实时获取外部数据（如汇率、天气信息）并存入表；在数据变更时通过触发器自动通知微服务；对数据库中的数据进行清洗后直接提交至外部 API 等。它为构建以数据库为中心的集成应用提供了强大而灵活的解决方案。
13+
14+
== 安装
15+
IvorySQL的安装包里已经集成了pgsql-http插件，如果使用安装包安装的IvorySQL，通常不需要再手动安装pgsql-http即可使用。其它安装方式可以参考下面的源码安装步骤。
16+
17+
[TIP]
18+
源码安装环境为 Ubuntu 24.04(x86_64)，环境中已经安装了IvorySQL5及以上版本，安装路径为/usr/local/ivorysql/ivorysql-5
19+
20+
=== 源码安装
21+
22+
** 安装依赖
23+
24+
对libcurl有依赖，libcurl的开发文件（例如 libcurl4-openssl-dev）需要提前安装上
25+
[literal]
26+
----
27+
#安装依赖
28+
sudo apt install libcurl4-openssl-dev
29+
----
30+
31+
** 编译安装
32+
33+
从https://github.com/pramsey/pgsql-http/releases/tag/v1.7.0 下载 1.7.0的源码包 pgsql-http-1.7.0.tar.gz
34+
[literal]
35+
----
36+
tar xvf pgsql-http-1.7.0.tar.gz
37+
cd pgsql-http-1.7.0
38+
# 确保pg_config在PATH里可以访问，eg: /usr/local/ivorysql/ivorysql-5/bin/pg_config
39+
make
40+
sudo make install
41+
----
42+
43+
== 创建Extension并确认http版本
44+
45+
psql 连接到数据库，执行如下命令：
46+
[literal]
47+
----
48+
ivorysql=# CREATE extension http;
49+
CREATE EXTENSION
50+
51+
ivorysql=# SELECT * FROM pg_available_extensions WHERE name = 'http';
52+
name | default_version | installed_version | comment
53+
-----------+-----------------+-------------------+-------------------------------------------------------------------------
54+
http | 1.7 | 1.7 | HTTP client for PostgreSQL, allows web page retrieval inside the database.
55+
(1 row)
56+
----
57+
58+
== 使用
59+
关于pgsql-http的使用，请参阅 https://github.com/pramsey/pgsql-http[pgsql-http官方文档]

0 commit comments

Comments
 (0)