Merge branch 'master' into master

Author: NotHimmel

CN/modules/ROOT/nav.adoc

@@ -19,7 +19,8 @@
 *** xref:master/5.4.adoc[pg_cron]
 *** xref:master/5.5.adoc[pgsql-http]
 *** xref:master/5.6.adoc[plpgsql_check]
-*** xref:master/5.8.adoc[PgAudit]
+*** xref:master/5.7.adoc[pgroonga]
+*** xref:master/5.8.adoc[pgaudit]
 ** IvorySQL架构设计
 *** 查询处理
 **** xref:master/6.1.1.adoc[双parser]
@@ -35,7 +36,8 @@
 **** xref:master/6.3.7.adoc[嵌套子函数]
 **** xref:master/6.3.8.adoc[Force View]
 **** xref:master/6.3.9.adoc[大小写转换]
-*** xref:master/6.4.adoc[国标GB18030]
+**** xref:master/6.3.10.adoc[sys_guid 函数]
+**** xref:master/6.3.11.adoc[空字符串转null]
 *** 内置函数
 **** xref:master/6.4.1.adoc[sys_context]
 **** xref:master/6.4.2.adoc[userenv]
@@ -60,6 +62,8 @@
 *** xref:master/7.17.adoc[17、NLS 参数]
 *** 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]
 ** IvorySQL贡献指南
 *** xref:master/8.1.adoc[社区贡献指南]
 *** xref:master/8.2.adoc[asciidoc语法快速参考]

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

@@ -17,6 +17,7 @@ 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 | 提供​非英语语言全文搜索功能，满足高性能应用的需求 | 中日韩等语言的全文搜索功能
 |====
 
 这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。

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/6.3.10.adoc

@@ -0,0 +1,21 @@
+:sectnums:
+:sectnumlevels: 5
+
+:imagesdir: ./_images
+
+= sys_guid() 函数
+
+== 目的
+
+IvorySQL的sys_guid() 是一个强大的随机数产生函数，它产生并返回一个由16个字节组成的数据库级别唯一的标识符(原始值)。
+
+== 实现说明
+
+IvorySQL的sys_guid()函数通过修改插件uuid-ossp的代码实现。为了充分利用uuid的多种基础库，采用如下逻辑：
+
+1. 如果系统有uuid-ossp，就使用uuid_make();
+2. 如果系统有uuid-e2fs，就使用 uuid_generate_random();
+3. 否则就调用 arc4random();
+
+同时修改代码使得IvorySQL能够自动载入uuid-ossp插件。
+

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

@@ -0,0 +1,73 @@
+:sectnums:
+:sectnumlevels: 5
+
+:imagesdir: ./_images
+
+= 空字符串转NULL功能
+
+== 目的
+
+在Oracle数据库中，空字符串('')被视为NULL值，这是Oracle的一个重要特性。为了兼容Oracle的这一行为，IvorySQL提供了空字符串转NULL功能。当启用该功能后，SQL语句中的空字符串将自动转换为NULL值，从而保证Oracle应用程序在IvorySQL上的行为一致性。
+
+== 实现说明
+
+参数 `ivorysql.enable_emptystring_to_NULL` 对应的GUC变量为 `enable_emptystring_to_NULL`。
+
+在文件 `ora_scan.l` 中可以看到对这个变量的使用：
+
+[source,c]
+----
+case xe:
+    yylval->str = litbufdup(yyscanner);
+    if (strcmp(yylval->str, "") == 0 &&
+        ORA_PARSER == compatible_db &&
+        enable_emptystring_to_NULL)
+    {
+        return NULL_P;
+    }
+    return SCONST;
+----
+
+其中 `xe` 代表被引号包围的字符串：
+
+----
+<xe> extended quoted strings (support backslash escape sequences)
+----
+
+上面代码的逻辑是，在词法分析时如果遇到空字符串，在空转NULL功能启用的情况下，返回 `NULL_P`，否则返回 `SCONST`。
+
+在语法分析文件 `ora_gram.y` 里，对语句 `insert into abc values('');` 是这样解析的：
+
+[source,c]
+----
+values_clause:
+    VALUES '(' expr_list ')'
+    {
+        SelectStmt *n = makeNode(SelectStmt);
+
+        n->valuesLists = list_make1($3);
+        $$ = (Node *) n;
+    }
+
+expr_list:      a_expr
+        {
+            $$ = list_make1($1);
+        }
+
+a_expr:       c_expr                      { $$ = $1; }
+
+c_expr:       AexprConst                  { $$ = $1; }
+
+AexprConst: Iconst
+       | Sconst
+           {
+               $$ = makeStringConst($1, @1);
+           }
+       | NULL_P
+           {
+               $$ = makeNullAConst(@1);
+           }
+----
+
+以上代码对词法分析时返回的 `NULL_P` 或者 `SCONST` 分别构建对应的节点进行处理。
+

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

@@ -5,7 +5,7 @@
 
 = **功能概述**
 
-IvorySQL提供兼容Oracle内置函数`SYS_CONTEXT('namespace', 'parameter' [, length ])`,
+IvorySQL提供兼容Oracle内置函数 ```SYS_CONTEXT('namespace', 'parameter' [, length ])``` ,
 返回当前时刻与给定上下文关联参数的值，可以在SQL和PLSQL语言中使用。
 
 提供以下命名空间：
@@ -16,8 +16,8 @@ IvorySQL提供兼容Oracle内置函数`SYS_CONTEXT('namespace', 'parameter' [, l
 
 == 实现原理
 
-SYS_CONTEXT的实现原理是通过动态查询系统表与postgres的内置函数，确保结果的实时性，
-使用 SECURITY INVOKER 确保函数以调用者的权限执行，避免权限提升问题。
+`SYS_CONTEXT` 的实现原理是通过动态查询系统表与postgres的内置函数，确保结果的实时性，
+使用 `SECURITY INVOKER` 确保函数以调用者的权限执行，避免权限提升问题。
 该方法的实现逻辑如下：
 ```sql
 CREATE OR REPLACE FUNCTION sys.sys_context(a varchar2, b varchar2)

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

@@ -5,8 +5,8 @@
 
 = **功能概述**
 
-IvorySQL提供兼容Oracle内置函数`USERENV('parameter')`,用于返回当前会话的相关信息。
-这是一个遗留函数，建议使用 SYS_CONTEXT 函数及其内置的 USERENV 命名空间来获取当前功能。
+IvorySQL提供兼容Oracle内置函数 ```USERENV('parameter')``` ,用于返回当前会话的相关信息。
+这是一个遗留函数，建议使用 `SYS_CONTEXT` 函数及其内置的 `USERENV` 命名空间来获取当前功能。
 
 == 实现原理
 

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

@@ -0,0 +1,36 @@
+:sectnums:
+:sectnumlevels: 5
+
+:imagesdir: ./_images
+
+= sys_guid() 函数
+
+== 目的
+
+IvorySQL的sys_guid() 是一个强大的随机数产生函数，它产生并返回一个由16个字节组成的数据库级别唯一的标识符(原始值)。
+
+== 使用示例
+
+```
+ivorysql=# select sys_guid() from dual;
+              sys_guid              
+------------------------------------
+ \x3ed9426c8a093442a38bea09a74f44a1
+(1 row)
+```
+
+== sys_guid函数在建表时可以作为主键
+
+```
+create table student
+(
+student_id raw(16) default sys_guid() primary key,
+student_name varchar2(100) not null
+);
+```
+
+== 新增数据时自动填充主键
+
+```
+insert into student(student_name) values ('Steven');
+```

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

@@ -0,0 +1,51 @@
+:sectnums:
+:sectnumlevels: 5
+
+:imagesdir: ./_images
+
+= 兼容Oracle 空字符串转NULL
+
+== 目的
+
+- 在 IvorySQL 的 Oracle 兼容模式下,支持将空字符串转换成NULL进行存储,提供与Oracle数据库一致的行为。
+
+== 功能说明
+
+- Oracle兼容模式下支持将空字符串转换成NULL进行存储。
+- 通过参数 `ivorysql.enable_emptystring_to_null` 控制该特性,默认值为 `on`。
+- 当该参数开启时,插入空字符串会自动转换为NULL值存储。
+- 可以通过 `IS NULL` 条件查询到转换后的NULL值。
+
+== 测试用例
+
+[literal]
+----
+-- 创建测试表
+ivorysql=# create table abc (id int);
+CREATE TABLE
+
+-- 查看空字符串转NULL参数状态
+ivorysql=# show ivorysql.enable_emptystring_to_null;
+ ivorysql.enable_emptystring_to_NULL
+-------------------------------------
+ on
+(1 row)
+
+-- 插入空字符串
+ivorysql=# insert into abc values('');
+INSERT 0 1
+
+-- 查询表数据,显示为NULL
+ivorysql=# select * from abc;
+ id
+\----
+
+(1 row)
+
+-- 使用IS NULL条件查询
+ivorysql=# select * from abc where id is null;
+ id
+\----
+
+(1 row)
+----

EN/modules/ROOT/nav.adoc

@@ -18,7 +18,8 @@
 ** xref:master/5.4.adoc[pg_cron]
 ** xref:master/5.5.adoc[pgsql-http]
 ** xref:master/5.6.adoc[plpgsql_check]
-** xref:master/5.8.adoc[PgAudit]
+** xref:master/5.7.adoc[pgroonga]
+** xref:master/5.8.adoc[pgaudit]
 * IvorySQL Architecture Design
 ** Query Processing
 *** xref:master/6.1.1.adoc[Dual Parser]
@@ -34,7 +35,8 @@
 *** xref:master/6.3.7.adoc[Nested Subfunctions]
 *** xref:master/6.3.8.adoc[Force View]
 *** xref:master/6.3.9.adoc[Case Conversion]
-** xref:master/6.4.adoc[GB18030 Character Set]
+*** xref:master/6.3.10.adoc[sys_guid Function]
+*** xref:master/6.3.11.adoc[Empty String to NULL]
 ** Built-in Functions
 *** xref:master/6.4.1.adoc[sys_context]
 *** xref:master/6.4.2.adoc[userenv]
@@ -59,6 +61,8 @@
 ** xref:master/7.17.adoc[17、NLS Parameters]
 ** xref:master/7.18.adoc[18、Force View]
 ** xref:master/7.19.adoc[19、Nested Subfunctions]
+** xref:master/7.20.adoc[20、sys_guid Function]
+** xref:master/7.21.adoc[21、Empty String to NULL]
 * xref:master/8.adoc[Community contribution]
 * xref:master/9.adoc[Tool Reference]
 * xref:master/10.adoc[FAQ]