Merge branch 'master' into pgroonga

OreoYang · web-flow · commit 45782a41990e · 2025-11-05T15:03:56.000+08:00
diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc
@@ -36,6 +36,7 @@
 **** 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.3.11.adoc[空字符串转null]
 *** 内置函数
 **** xref:master/6.4.1.adoc[sys_context]
 **** xref:master/6.4.2.adoc[userenv]
@@ -61,6 +62,7 @@
 *** 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语法快速参考]
diff --git a/CN/modules/ROOT/pages/master/6.3.11.adoc b/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` 分别构建对应的节点进行处理。
+
diff --git a/CN/modules/ROOT/pages/master/7.20.adoc b/CN/modules/ROOT/pages/master/7.20.adoc
@@ -12,7 +12,7 @@ IvorySQL的sys_guid() 是一个强大的随机数产生函数，它产生并返
 == 使用示例
 
 ```
-highgo=# select sys_guid() from dual;
+ivorysql=# select sys_guid() from dual;
               sys_guid              
 ------------------------------------
  \x3ed9426c8a093442a38bea09a74f44a1
diff --git a/CN/modules/ROOT/pages/master/7.21.adoc b/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)
+----
diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc
@@ -35,6 +35,7 @@
 *** xref:master/6.3.8.adoc[Force View]
 *** xref:master/6.3.9.adoc[Case Conversion]
 *** 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]
@@ -60,6 +61,7 @@
 ** 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]
diff --git a/EN/modules/ROOT/pages/master/6.3.11.adoc b/EN/modules/ROOT/pages/master/6.3.11.adoc
@@ -0,0 +1,73 @@
+:sectnums:
+:sectnumlevels: 5
+
+:imagesdir: ./_images
+
+= Empty String to NULL Conversion
+
+== Purpose
+
+In Oracle databases, empty strings ('') are treated as NULL values, which is an important Oracle feature. To maintain compatibility with this Oracle behavior, IvorySQL provides the empty string to NULL conversion functionality. When this feature is enabled, empty strings in SQL statements are automatically converted to NULL values, ensuring behavioral consistency for Oracle applications running on IvorySQL.
+
+== Implementation
+
+The parameter `ivorysql.enable_emptystring_to_NULL` corresponds to the GUC variable `enable_emptystring_to_NULL`.
+
+In the file `ora_scan.l`, you can see how this variable is used:
+
+[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;
+----
+
+Where `xe` represents strings enclosed in quotes:
+
+----
+<xe> extended quoted strings (support backslash escape sequences)
+----
+
+The logic of the above code is that during lexical analysis, if an empty string is encountered and the empty-to-NULL conversion feature is enabled, it returns `NULL_P`; otherwise, it returns `SCONST`.
+
+In the grammar analysis file `ora_gram.y`, the statement `insert into abc values('');` is parsed as follows:
+
+[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);
+           }
+----
+
+The above code constructs corresponding nodes to handle `NULL_P` or `SCONST` returned from the lexical analysis.
+
diff --git a/EN/modules/ROOT/pages/master/7.20.adoc b/EN/modules/ROOT/pages/master/7.20.adoc
@@ -12,7 +12,7 @@ IvorySQL's sys_guid() is a powerful random number generation function that gener
 == Usage example
 
 ```
-highgo=# select sys_guid() from dual;
+ivorysql=# select sys_guid() from dual;
               sys_guid              
 ------------------------------------
  \x3ed9426c8a093442a38bea09a74f44a1
diff --git a/EN/modules/ROOT/pages/master/7.21.adoc b/EN/modules/ROOT/pages/master/7.21.adoc
@@ -0,0 +1,52 @@
+:sectnums:
+:sectnumlevels: 5
+
+:imagesdir: ./_images
+
+= Oracle Compatible Empty String to NULL
+
+== Purpose
+
+- In IvorySQL's Oracle compatibility mode, support converting empty strings to NULL for storage, providing behavior consistent with Oracle Database.
+
+== Feature Description
+
+- Oracle compatibility mode supports converting empty strings to NULL for storage.
+- The feature is controlled by parameter `ivorysql.enable_emptystring_to_null`, with default value `on`.
+- When this parameter is enabled, inserting an empty string will automatically convert it to NULL value for storage.
+- NULL values after conversion can be queried using the `IS NULL` condition.
+
+== Test Cases
+
+[literal]
+----
+-- Create test table
+ivorysql=# create table abc (id int);
+CREATE TABLE
+
+-- Check empty string to NULL parameter status
+ivorysql=# show ivorysql.enable_emptystring_to_null;
+ ivorysql.enable_emptystring_to_NULL
+-------------------------------------
+ on
+(1 row)
+
+-- Insert empty string
+ivorysql=# insert into abc values('');
+INSERT 0 1
+
+-- Query table data, displays as NULL
+ivorysql=# select * from abc;
+ id
+\----
+
+(1 row)
+
+-- Query using IS NULL condition
+ivorysql=# select * from abc where id is null;
+ id
+\----
+
+(1 row)
+----
+
