Merge branch 'master' into postgis

Author: yuanyl630

CN/modules/ROOT/nav.adoc

@@ -20,6 +20,10 @@
 *** xref:master/5.4.adoc[pg_cron]
 *** xref:master/5.5.adoc[pgsql-http]
 *** xref:master/5.6.adoc[plpgsql_check]
+*** xref:master/5.7.adoc[pgroonga]
+*** xref:master/5.8.adoc[pgaudit]
+*** xref:master/5.9.adoc[pgrouting]
+*** xref:master/5.10.adoc[system_stats]
 ** IvorySQL架构设计
 *** 查询处理
 **** xref:master/6.1.1.adoc[双parser]
@@ -36,7 +40,8 @@
 **** xref:master/6.3.8.adoc[Force View]
 **** xref:master/6.3.9.adoc[大小写转换]
 **** xref:master/6.3.10.adoc[sys_guid 函数]
-*** xref:master/6.4.adoc[国标GB18030]
+**** xref:master/6.3.11.adoc[空字符串转null]
+**** xref:master/6.3.12.adoc[CALL INTO]
 *** 内置函数
 **** xref:master/6.4.1.adoc[sys_context]
 **** xref:master/6.4.2.adoc[userenv]
@@ -62,6 +67,8 @@
 *** xref:master/7.18.adoc[18、Force View]
 *** xref:master/7.19.adoc[19、嵌套子函数]
 *** xref:master/7.20.adoc[20、sys_guid 函数]
+*** xref:master/7.21.adoc[21、空字符串转null]
+*** xref:master/7.22.adoc[22、CALL INTO]
 ** IvorySQL贡献指南
 *** xref:master/8.1.adoc[社区贡献指南]
 *** xref:master/8.2.adoc[asciidoc语法快速参考]

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

@@ -18,8 +18,11 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
 | xref:master/5.4.adoc[pg_cron]​ | 1.6.0 | 提供数据库内部的定时任务调度功能，支持定期执行SQL语句 | 数据清理、定期统计、自动化维护任务
 | xref:master/5.5.adoc[pgsql-http]​ | 1.7.0 | 允许在SQL中发起HTTP请求，与外部Web服务进行交互 | 数据采集、API集成、微服务调用
 | xref:master/5.6.adoc[plpgsql_check] | 2.8 | 提供PL/pgSQL代码的静态分析功能，可在开发阶段发现潜在错误 | 存储过程开发、代码质量检查、调试优化
+| xref:master/5.7.adoc[pgroonga] | 4.0.4 | 提供​非英语语言全文搜索功能，满足高性能应用的需求 | 中日韩等语言的全文搜索功能
+| xref:master/5.8.adoc[pgaudit] | 18.0 | 提供细粒度的审计功能，记录数据库操作日志，便于安全审计和合规性检查 | 数据库安全审计、合规性检查、审计报告生成
+| xref:master/5.9.adoc[pgrouting] | 3.8.0 | 提供地理空间数据的路由计算功能，支持多种算法和数据格式 | 地理空间分析、路径规划、物流优化
 |====
 
 这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。
 
-我们也将持续扩展和丰富 IvorySQL 的插件生态，欢迎社区开发者提交新的插件适配建议或代码贡献。如需了解更多每个插件的详细使用方法和最新兼容版本，请参阅各插件对应的文档章节。
+我们也将持续扩展和丰富 IvorySQL 的插件生态，欢迎社区开发者提交新的插件适配建议或代码贡献。如需了解更多每个插件的详细使用方法和最新兼容版本，请参阅各插件对应的文档章节。

CN/modules/ROOT/pages/master/5.10.adoc

@@ -0,0 +1,146 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+= system_stats
+
+== 概述
+system_stats 是一个 PostgreSQL 扩展，提供用于访问系统级统计信息的函数，可用于监控场景。
+
+== 安装
+
+[TIP]
+源码安装环境为 Ubuntu 24.04(x86_64)，环境中已经安装了IvorySQL5及以上版本，安装路径为/usr/local/ivorysql/ivorysql-5
+
+=== 源码安装
+
+[literal]
+----
+# 从 https://github.com/EnterpriseDB/system_stats/releases/tag/v3.2 下载 3.2 的源码包 v3.2.zip
+unzip v3.2.zip
+cd system_stats-3.2
+
+# 编译安装插件
+make PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config
+make PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config install
+----
+
+== 创建插件并确认版本
+
+psql 连接到数据库，执行如下命令：
+[literal]
+----
+ivorysql=# CREATE EXTENSION system_stats;
+CREATE EXTENSION
+
+ivorysql=# SELECT * FROM pg_available_extensions WHERE name = 'system_stats';
+     name     | default_version | installed_version |                    comment                    
+--------------+-----------------+-------------------+-----------------------------------------------
+ system_stats | 3.0             | 3.0               | EnterpriseDB system statistics for PostgreSQL
+(1 row)
+----
+
+== 使用
+
+[literal]
+----
+ivorysql=> select pg_sys_os_info() from dual;
+                              pg_sys_os_info                              
+--------------------------------------------------------------------------
+ ("""Ubuntu 24.04.1 LTS""                                                +
+ ","Linux 6.14.0-29-generic",Ubuntu,"(none)",5568,292,532,x86_64,,864122)
+(1 row)
+
+
+
+ivorysql=> select pg_sys_cpu_info() from dual;
+                                                           pg_sys_cpu_info                                                           
+-------------------------------------------------------------------------------------------------------------------------------------
+ (GenuineIntel,"GenuineIntel model 154 family 6","12th Gen Intel(R) Core(TM) i7-1260P",,0,2,1,x86_64,2496000000,,,,48,32,1280,18432)
+(1 row)
+
+
+ivorysql=> select pg_sys_cpu_usage_info() from dual;
+ pg_sys_cpu_usage_info 
+-----------------------
+ (0,0,0,100,0,0,0,,,,)
+(1 row)
+
+
+ivorysql=> select pg_sys_memory_info() from dual;
+                                pg_sys_memory_info                                 
+-----------------------------------------------------------------------------------
+ (4055482368,3911159808,144322560,4055887872,233725952,3822161920,2638602240,,,,,)
+(1 row)
+
+
+ivorysql=> select pg_sys_io_analysis_info() from dual;
+                    pg_sys_io_analysis_info                    
+---------------------------------------------------------------
+ (loop0,15,0,21504,0,1,0)
+ (loop1,1362,0,27916288,0,680,0)
+ (loop2,175,0,3354624,0,131,0)
+ (loop3,141,0,1827840,0,83,0)
+ (loop4,918,0,32752640,0,212,0)
+ (loop5,156,0,2617344,0,67,0)
+ (loop6,3707,0,131992576,0,828,0)
+ (loop7,243,0,4321280,0,95,0)
+ (fd0,0,0,0,0,0,0)
+ (sda,639286,1580583,26547332096,240138948608,402702,2744653)
+ (sda1,561,0,22966272,0,61,0)
+ (sda2,636820,1580583,26491053056,240138948608,402316,2744653)
+ (sr0,87,0,3219456,0,45,0)
+ (sr1,0,0,0,0,0,0)
+ (loop8,228,0,2491392,0,120,0)
+ (loop10,2333,0,36571136,0,1628,0)
+ (loop9,3730,0,66532352,0,3973,0)
+ (loop11,87,0,709632,0,50,0)
+ (loop12,156,0,1948672,0,52,0)
+ (loop14,2579,0,97446912,0,2083,0)
+ (loop13,30,0,102400,0,14,0)
+ (loop15,82,0,1189888,0,117,0)
+ (loop16,1357,0,28335104,0,500,0)
+ (loop17,110,0,2187264,0,93,0)
+ (loop18,129,0,2355200,0,28,0)
+ (loop19,110,0,2202624,0,55,0)
+(26 rows)
+
+
+ivorysql=> select pg_sys_disk_info() from dual;
+                                 pg_sys_disk_info                                 
+----------------------------------------------------------------------------------
+ (/,/dev/sda2,,,ext4,105086115840,50903396352,48797392896,6553600,619735,5933865)
+(1 row)
+
+
+ivorysql=> select pg_sys_load_avg_info() from dual;
+ pg_sys_load_avg_info 
+----------------------
+ (0,0,0,)
+(1 row)
+
+
+ivorysql=> select pg_sys_process_info() from dual;
+ pg_sys_process_info 
+---------------------
+ (294,1,201,0,0)
+(1 row)
+
+
+ivorysql=> select pg_sys_network_info() from dual;
+                             pg_sys_network_info                             
+-----------------------------------------------------------------------------
+ (lo,127.0.0.1,1071575,5643,0,0,1071575,5643,0,0,0)
+ (ens33,192.168.198.128,619877515,1490961,0,161,5540250106,4345449,0,0,1000)
+(2 rows)
+
+
+ivorysql=> select pg_sys_cpu_memory_by_process() from dual;
+                     pg_sys_cpu_memory_by_process                      
+-----------------------------------------------------------------------
+ (1,"(systemd)",864793,0,0.34,13840384)
+ (2,"(kthreadd)",864793,0,0,0)
+ (3,"(pool_workqueue_release)",864793,0,0,0)
+ (4,"(kworker/R-rcu_gp)",864793,0,0,0)
+......
+----

CN/modules/ROOT/pages/master/5.7.adoc

@@ -0,0 +1,94 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+= PGroonga
+
+== 概述
+PostgreSQL 内置了全文搜索功能，但在处理​​大规模数据​​、​​复杂查询​​以及​​非英语语言（特别是中日韩等 CJK 语言）​​ 时，其功能和性能可能无法满足高性能应用的需求。
+
+PGroonga 应运而生，它是一个 PostgreSQL 的扩展插件，将 ​​Groonga​​ 这款高性能的全功能全文搜索引擎与 PostgreSQL 数据库深度融合。Groonga 本身是一个优秀的开源搜索引擎，以其极致的速度和丰富的功能著称，尤其擅长处理多语言文本。PGroonga 的使命就是将 Groonga 的强大能力无缝地带入 PostgreSQL 的世界，为用户提供远超原生全文搜索的体验。
+
+== 安装
+[NOTE]
+IvorySQL的安装包里已经集成了PGroonga插件，如果使用安装包安装的IvorySQL，通常不需要再手动安装PGroonga，直接跳过安装步骤即可。
+
+用户可从 https://pgroonga.github.io/install[PGroonga package安装] 页面选择适合自己的方式进行PGroonga安装。
+
+IvorySQL社区提供了源码安装步骤，下面以PGroonga v4.0.4为例进行演示。
+
+=== 安装依赖
+
+环境
+```  
+  操作系统：Ubuntu 24.04
+  CPU架构：x86_64
+  IvorySQL: v5.0
+```
+
+==== 安装 msgpack-c
+
+编译PGroonga，有个配置选项：HAVE_MSGPACK=1，它是用于支持WAL，使用这个选项需要安装msgpack-c 1.4.1或者更高版本。
+
+```
+  sudo apt install libmsgpack-dev
+```
+==== 安装 Groonga
+
+确保Groonga >= 14.0.0
+
+```
+  sudo apt install groonga libgroonga-dev
+```
+验证Groonga安装成功
+```bash
+highgo@ubuntu:~/work/IvorySQL/inst$ groonga --version
+  Groonga 15.1.7 [Linux,x86_64,utf8,match-escalation-threshold=0,nfkc,mecab,message-pack,mruby,onigmo,zlib,lz4,zstandard,epoll,apache-arrow,xxhash,blosc,h3,simdjson,llama.cpp]
+```
+
+
+=== 编译安装PGroonga
+
+==== 下载解压源码
+
+```bash
+  wget https://packages.groonga.org/source/pgroonga/pgroonga-4.0.4.tar.gz
+  tar xvf pgroonga-4.0.4.tar.gz
+  cd pgroonga-4.0.4
+```
+==== 编译
+运行make前确保`pg_config`命令的路径在`PATH`环境变量里，例如IvorySQL安装的路径是`~/work/IvorySQL/inst`，则环境变量设置如下：
+
+```bash
+  export PGHOME=~/work/IvorySQL/inst
+  export PGDATA=$PGHOME/data
+  export PATH=$PGHOME/bin:$PATH
+```
+然后执行以下命令进行编译和安装：
+```bash
+  make HAVE_MSGPACK=1
+  make install
+```
+
+== 创建Extension并确认PGroonga版本
+
+
+psql 连接到数据库的pg模式下，执行命令：
+```sql
+postgres=# CREATE extension pgroonga;
+CREATE EXTENSION
+postgres=# SELECT * FROM pg_available_extensions WHERE name = 'pgroonga';
+   name   | default_version | installed_version |                                    comment
+----------+-----------------+-------------------+--------------------------------------------------------------------------------
+ pgroonga | 4.0.4           | 4.0.4             | Super fast and all languages supported full text search index based on Groonga
+(1 row)
+
+postgres=# select version();
+                                    version
+--------------------------------------------------------------------------------
+ PostgreSQL (IvorySQL 5.0) 18.0 on x86_64-linux, compiled by gcc-13.3.0, 64-bit
+(1 row)
+```
+
+== 使用
+关于PGroonga的使用，请参阅 https://pgroonga.github.io/tutorial[PGroonga官方文档]

CN/modules/ROOT/pages/master/5.8.adoc

@@ -0,0 +1,107 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+= PgAudit
+
+== 概述
+
+PgAudit 是一个审计扩展，可以为 DDL、DML、DCL 等关键操作生成可追溯的日志记录。通过审计日志，数据库管理员能够满足合规要求、及时发现异常行为，并在出现问题时快速定位责任主体与影响范围。
+
+== 功能特点
+
+* *全面审计能力*：记录 `SELECT`、`INSERT`、`UPDATE`、`DELETE`、DDL 命令以及权限变更等操作，帮助构建完整的操作轨迹。
+* *灵活的审计维度*：支持全局审计、角色审计与对象审计，可按用户、角色、模式或具体操作类型进行精细化配置。
+* *平滑集成*：复用 PostgreSQL 标准日志子系统，可与 `syslog`、`logrotate` 等工具联动，兼容现有日志采集与分析方案。
+* *合规支撑*：提供结构化审计日志，便于生成符合金融、政企等行业规范的审计报告。
+* *安全增强*：通过记录和分析数据库活动，及时发现未授权访问、异常 DML 或潜在数据泄露风险。
+* *运维优化*：辅助回放操作行为、定位性能瓶颈，支撑 SQL 优化与问题排查。
+
+== 安装部署
+
+=== 环境准备
+
+* 已安装的 IvorySQL 数据库。
+* 编译工具链：`gcc`、`make`、`tar` 等。
+* 数据库管理员权限，用于修改 `ivorysql.conf` 并重启数据库实例。
+
+=== 编译安装 PgAudit
+
+以 PgAudit 18.0 为例：
+
+[source,shell]
+----
+wget https://github.com/pgaudit/pgaudit/archive/refs/tags/18.0.tar.gz
+tar -xf 18.0.tar.gz
+cd pgaudit-18.0
+make install USE_PGXS=1 PG_CONFIG=$PGHOME/bin/pg_config
+----
+
+上述命令依赖环境变量 `PGHOME` 指向安装好的 IvorySQL 主目录。安装成功后，`pgaudit.so` 会被放置到 IvorySQL 的扩展目录中。
+
+=== 注册扩展前的基础配置
+
+修改 `ivorysql.conf`，启用插件并设置常用参数：
+----
+shared_preload_libraries = 'pgaudit'   # 需实例重启生效
+pgaudit.log = 'read, write, ddl'       # 审计范围示例，可按需调整
+----
+
+重启数据库实例，使共享库配置生效。
+
+=== 创建扩展并验证
+
+[source,sql]
+----
+CREATE EXTENSION IF NOT EXISTS pgaudit;
+SELECT name,
+       default_version,
+       installed_version,
+       comment
+  FROM pg_available_extensions
+ WHERE name = 'pgaudit';
+----
+
+若返回的 `installed_version` 与期望版本一致，说明扩展安装成功。
+
+== 使用
+
+执行如下sql示例：
+
+[source,sql]
+----
+CREATE TABLE audit_demo(id serial PRIMARY KEY, info text);
+INSERT INTO audit_demo(info) VALUES ('pgaudit test');
+SELECT * FROM audit_demo;
+UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1;
+DELETE FROM audit_demo WHERE id = 1;
+----
+
+在数据库服务器上查看审计日志：
+
+[source,shell]
+----
+tail -f $PGDATA/log/*.log | grep 'AUDIT:'
+----
+
+[source,text]
+----
+2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,CREATE SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,CREATE TABLE,TABLE,public.audit_demo,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,CREATE INDEX,INDEX,public.audit_demo_pkey,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+2025-10-31 15:56:32.113 CST [11451] LOG:  AUDIT: SESSION,1,1,DDL,ALTER SEQUENCE,SEQUENCE,public.audit_demo_id_seq,"CREATE TABLE audit_demo(id serial PRIMARY KEY, info text)",<not logged>
+2025-10-31 15:56:32.117 CST [11451] LOG:  AUDIT: SESSION,2,1,WRITE,INSERT,,,INSERT INTO audit_demo(info) VALUES ('pgaudit test'),<not logged>
+2025-10-31 15:56:32.121 CST [11451] LOG:  AUDIT: SESSION,3,1,READ,SELECT,,,SELECT * FROM audit_demo,<not logged>
+2025-10-31 15:56:32.122 CST [11451] LOG:  AUDIT: SESSION,4,1,WRITE,UPDATE,,,UPDATE audit_demo SET info = 'pgaudit update' WHERE id = 1,<not logged>
+2025-10-31 15:56:32.127 CST [11451] LOG:  AUDIT: SESSION,5,1,WRITE,DELETE,,,DELETE FROM audit_demo WHERE id = 1,<not logged>
+----
+
+若想记录参数的值，打开`pgaudit.log_parameter = 'on'`，效果如下：
+[source,text]
+----
+ivorysql=# SHOW pgaudit.log_parameter;
+pgaudit.log_parameter
+-----------------------
+on
+(1 row)
+----