doc: Clarify that empty COMMENT string removes the comment.

Clarify the documentation of COMMENT ON to state that specifying an empty
string is treated as NULL, meaning that the comment is removed.

This makes the behavior explicit and avoids possible confusion about how
empty strings are handled.

Also adds regress test cases that use empty string to remove a comment.

Backpatch to all supported versions.

Author: Chao Li <lic@highgo.com>
Reviewed-by: Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Shengbin Zhao <zshengbin91@gmail.com>
Reviewed-by: Jim Jones <jim.jones@uni-muenster.de>
Reviewed-by: zhangqiang <zhang_qiang81@163.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Discussion: https://postgr.es/m/26476097-B1C1-4BA8-AA92-0AD0B8EC7190@gmail.com
Backpatch-through: 14

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index 8d81244910ba7ea393ce26c6e4003f03c205e949..fa71144c9145b887b32fea59b75159def523d0e1 100644 (file)
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -80,14 +80,16 @@ COMMENT ON
   <title>Description</title>
 
   <para>
-   <command>COMMENT</command> stores a comment about a database object.
+   <command>COMMENT</command> stores, replaces, or removes the comment on a
+   database object.
   </para>
 
   <para>
-   Only one comment string is stored for each object, so to modify a comment,
-   issue a new <command>COMMENT</command> command for the same object.  To remove a
-   comment, write <literal>NULL</literal> in place of the text string.
-   Comments are automatically dropped when their object is dropped.
+   Only one comment string is stored for each object.  Issuing a new
+   <command>COMMENT</command> command for the same object replaces the
+   existing comment.  Specifying <literal>NULL</literal> or an empty
+   string (<literal>''</literal>) removes the comment.  Comments are
+   automatically dropped when their object is dropped.
   </para>
 
   <para>
@@ -266,7 +268,8 @@ COMMENT ON
     <term><replaceable class="parameter">string_literal</replaceable></term>
     <listitem>
      <para>
-      The new comment contents, written as a string literal.
+      The new comment contents, written as a string literal.  An empty string
+      (<literal>''</literal>) removes the comment.
      </para>
     </listitem>
    </varlistentry>
@@ -275,7 +278,7 @@ COMMENT ON
     <term><literal>NULL</literal></term>
     <listitem>
      <para>
-      Write <literal>NULL</literal> to drop the comment.
+      Write <literal>NULL</literal> to remove the comment.
      </para>
     </listitem>
    </varlistentry>
@@ -362,6 +365,7 @@ COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transform between hstore
 COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
 COMMENT ON TYPE complex IS 'Complex number data type';
 COMMENT ON VIEW my_view IS 'View of departmental costs';
+COMMENT ON VIEW my_view IS NULL;
 </programlisting></para>
  </refsect1>
 

diff --git a/src/test/regress/expected/create_index.out b/src/test/regress/expected/create_index.out
index c743fc769cbe1baf7f77cacea8313a62f308946f..55538c4c41e88271cb465ebdaf5933d7a7787376 100644 (file)
--- a/src/test/regress/expected/create_index.out
+++ b/src/test/regress/expected/create_index.out
@@ -32,6 +32,20 @@ COMMENT ON INDEX six_wrong IS 'bad index';
 ERROR:  relation "six_wrong" does not exist
 COMMENT ON INDEX six IS 'good index';
 COMMENT ON INDEX six IS NULL;
+SELECT obj_description('six'::regclass, 'pg_class') IS NULL AS six_comment_is_null;
+ six_comment_is_null 
+---------------------
+ t
+(1 row)
+
+COMMENT ON INDEX six IS 'add the comment back';
+COMMENT ON INDEX six IS ''; -- empty string removes the comment, same as NULL
+SELECT obj_description('six'::regclass, 'pg_class') IS NULL AS six_comment_is_null;
+ six_comment_is_null 
+---------------------
+ t
+(1 row)
+
 --
 -- BTREE partial indices
 --

diff --git a/src/test/regress/expected/create_role.out b/src/test/regress/expected/create_role.out
index 46d4f9efe997ebe3c4c8516d04d12c820c8502ae..5d0f21820edde89e03feaddf2f8a226c21e925ff 100644 (file)
--- a/src/test/regress/expected/create_role.out
+++ b/src/test/regress/expected/create_role.out
@@ -102,6 +102,33 @@ CREATE ROLE regress_rolecreator CREATEROLE;
 CREATE ROLE regress_hasprivs CREATEROLE LOGIN INHERIT CONNECTION LIMIT 5;
 -- ok, we should be able to modify a role we created
 COMMENT ON ROLE regress_hasprivs IS 'some comment';
+SELECT shobj_description('regress_hasprivs'::regrole, 'pg_authid') IS NOT NULL AS has_comment;
+ has_comment 
+-------------
+ t
+(1 row)
+
+COMMENT ON ROLE regress_hasprivs IS NULL;
+SELECT shobj_description('regress_hasprivs'::regrole, 'pg_authid') IS NULL AS no_comment;
+ no_comment 
+------------
+ t
+(1 row)
+
+COMMENT ON ROLE regress_hasprivs IS 'add the comment back';
+SELECT shobj_description('regress_hasprivs'::regrole, 'pg_authid') IS NOT NULL AS has_comment;
+ has_comment 
+-------------
+ t
+(1 row)
+
+COMMENT ON ROLE regress_hasprivs IS ''; -- empty string removes the comment, same as NULL
+SELECT shobj_description('regress_hasprivs'::regrole, 'pg_authid') IS NULL AS no_comment;
+ no_comment 
+------------
+ t
+(1 row)
+
 ALTER ROLE regress_hasprivs RENAME TO regress_tenant;
 ALTER ROLE regress_tenant NOINHERIT NOLOGIN CONNECTION LIMIT 7;
 -- fail, we should be unable to modify a role we did not create

diff --git a/src/test/regress/sql/create_index.sql b/src/test/regress/sql/create_index.sql
index eabc9623b20615bf1fafd10fa3b5244c3fc4a3a6..82e4062a215f84bd284c1aaa66ec087df29ae6d8 100644 (file)
--- a/src/test/regress/sql/create_index.sql
+++ b/src/test/regress/sql/create_index.sql
@@ -45,6 +45,10 @@ CREATE INDEX six ON shighway USING btree (name text_ops);
 COMMENT ON INDEX six_wrong IS 'bad index';
 COMMENT ON INDEX six IS 'good index';
 COMMENT ON INDEX six IS NULL;
+SELECT obj_description('six'::regclass, 'pg_class') IS NULL AS six_comment_is_null;
+COMMENT ON INDEX six IS 'add the comment back';
+COMMENT ON INDEX six IS ''; -- empty string removes the comment, same as NULL
+SELECT obj_description('six'::regclass, 'pg_class') IS NULL AS six_comment_is_null;
 
 --
 -- BTREE partial indices

diff --git a/src/test/regress/sql/create_role.sql b/src/test/regress/sql/create_role.sql
index 4491a28a8ae99894e846a0dcd0fc0aa1a43389b6..b22f9c6f50aa38b339c8ff6c4dba8eb3da6881ad 100644 (file)
--- a/src/test/regress/sql/create_role.sql
+++ b/src/test/regress/sql/create_role.sql
@@ -92,6 +92,13 @@ CREATE ROLE regress_hasprivs CREATEROLE LOGIN INHERIT CONNECTION LIMIT 5;
 
 -- ok, we should be able to modify a role we created
 COMMENT ON ROLE regress_hasprivs IS 'some comment';
+SELECT shobj_description('regress_hasprivs'::regrole, 'pg_authid') IS NOT NULL AS has_comment;
+COMMENT ON ROLE regress_hasprivs IS NULL;
+SELECT shobj_description('regress_hasprivs'::regrole, 'pg_authid') IS NULL AS no_comment;
+COMMENT ON ROLE regress_hasprivs IS 'add the comment back';
+SELECT shobj_description('regress_hasprivs'::regrole, 'pg_authid') IS NOT NULL AS has_comment;
+COMMENT ON ROLE regress_hasprivs IS ''; -- empty string removes the comment, same as NULL
+SELECT shobj_description('regress_hasprivs'::regrole, 'pg_authid') IS NULL AS no_comment;
 ALTER ROLE regress_hasprivs RENAME TO regress_tenant;
 ALTER ROLE regress_tenant NOINHERIT NOLOGIN CONNECTION LIMIT 7;