From cde87b5a3574af5ebf9d28e051a0ab2df4eaccbb Mon Sep 17 00:00:00 2001 From: yuan li Date: Mon, 3 Nov 2025 17:20:39 +0800 Subject: [PATCH 1/3] add usage document --- CN/modules/ROOT/nav.adoc | 1 + CN/modules/ROOT/pages/master/7.20.adoc | 2 +- CN/modules/ROOT/pages/master/7.21.adoc | 51 +++++++++++++++++++++++++ EN/modules/ROOT/nav.adoc | 1 + EN/modules/ROOT/pages/master/7.20.adoc | 2 +- EN/modules/ROOT/pages/master/7.21.adoc | 52 ++++++++++++++++++++++++++ 6 files changed, 107 insertions(+), 2 deletions(-) create mode 100644 CN/modules/ROOT/pages/master/7.21.adoc create mode 100644 EN/modules/ROOT/pages/master/7.21.adoc diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index db182ed..5dd266d 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -61,6 +61,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/7.20.adoc b/CN/modules/ROOT/pages/master/7.20.adoc index 70e6380..4e1af6a 100644 --- 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 new file mode 100644 index 0000000..f70b977 --- /dev/null +++ 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值。 + +== 测试用例 + +[source,sql] +---- +-- 创建测试表 +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 index d5fa57f..5f34a91 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -60,6 +60,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/7.20.adoc b/EN/modules/ROOT/pages/master/7.20.adoc index 37c67fb..6493959 100644 --- 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 new file mode 100644 index 0000000..e0eae7c --- /dev/null +++ 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 + +[source,sql] +---- +-- 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) +---- + From 79af35d5c6d49cb7e19221ee10641a324346986b Mon Sep 17 00:00:00 2001 From: yuan li Date: Mon, 3 Nov 2025 17:54:07 +0800 Subject: [PATCH 2/3] fix format issue --- CN/modules/ROOT/pages/master/7.21.adoc | 6 +++--- EN/modules/ROOT/pages/master/7.21.adoc | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/CN/modules/ROOT/pages/master/7.21.adoc b/CN/modules/ROOT/pages/master/7.21.adoc index f70b977..1686ff1 100644 --- a/CN/modules/ROOT/pages/master/7.21.adoc +++ b/CN/modules/ROOT/pages/master/7.21.adoc @@ -18,7 +18,7 @@ == 测试用例 -[source,sql] +[literal] ---- -- 创建测试表 ivorysql=# create table abc (id int); @@ -38,14 +38,14 @@ 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/pages/master/7.21.adoc b/EN/modules/ROOT/pages/master/7.21.adoc index e0eae7c..3c888b2 100644 --- a/EN/modules/ROOT/pages/master/7.21.adoc +++ b/EN/modules/ROOT/pages/master/7.21.adoc @@ -18,7 +18,7 @@ == Test Cases -[source,sql] +[literal] ---- -- Create test table ivorysql=# create table abc (id int); @@ -38,14 +38,14 @@ 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) ---- From cbd5e7e61cf8ca22dbb15a9301646d71a3226833 Mon Sep 17 00:00:00 2001 From: yuan li Date: Tue, 4 Nov 2025 10:07:17 +0800 Subject: [PATCH 3/3] add implementation document --- CN/modules/ROOT/nav.adoc | 2 +- CN/modules/ROOT/pages/master/6.3.11.adoc | 73 ++++++++++++++++++++++++ EN/modules/ROOT/nav.adoc | 2 +- EN/modules/ROOT/pages/master/6.3.11.adoc | 73 ++++++++++++++++++++++++ 4 files changed, 148 insertions(+), 2 deletions(-) create mode 100644 CN/modules/ROOT/pages/master/6.3.11.adoc create mode 100644 EN/modules/ROOT/pages/master/6.3.11.adoc diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 5dd266d..6b7078c 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -35,7 +35,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.4.adoc[国标GB18030] +**** xref:master/6.3.11.adoc[空字符串转null] *** 内置函数 **** xref:master/6.4.1.adoc[sys_context] **** xref:master/6.4.2.adoc[userenv] diff --git a/CN/modules/ROOT/pages/master/6.3.11.adoc b/CN/modules/ROOT/pages/master/6.3.11.adoc new file mode 100644 index 0000000..fc10958 --- /dev/null +++ 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` 代表被引号包围的字符串： + +---- + 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/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index 5f34a91..a61931b 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -34,7 +34,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.4.adoc[GB18030 Character Set] +*** 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] diff --git a/EN/modules/ROOT/pages/master/6.3.11.adoc b/EN/modules/ROOT/pages/master/6.3.11.adoc new file mode 100644 index 0000000..a34ab01 --- /dev/null +++ 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: + +---- + 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. +