From: Chao Li <li.evan.chao@gmail.com>
To: Fujii Masao <masao.fujii@gmail.com>
Cc: David G. Johnston <david.g.johnston@gmail.com>
Cc: Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Cc: zhang_qiang81@163.com
Subject: Re: doc: Clarify that empty COMMENT string removes the comment
Date: Tue, 3 Mar 2026 11:16:59 +0800
Message-ID: <F88CAD6A-7CD2-445D-AE79-76F3F827B296@gmail.com> (raw)
In-Reply-To: <CAHGQGwFSxdXh-LsSTj+EE6VhJm6XjpgiH42kUsUDxgXViFn-Cg@mail.gmail.com>
References: <26476097-B1C1-4BA8-AA92-0AD0B8EC7190@gmail.com>
<CAExHW5vqMWdZ0wh7hFvGascGmpS7sYDTb26Bw2sGY3R4fOz3sw@mail.gmail.com>
<CAKFQuwbT4RpRtEmygJyLqnjs7tgtZ4mHRX9-MJxQ3ZBu+2b+UQ@mail.gmail.com>
<9E0B8DED-4A75-4E93-B731-62A4E7F92B2C@gmail.com>
<CAKFQuwb3-nGGOTR9vwQSr2GBgdaAxipM+iuTdXB00JKGkndKyw@mail.gmail.com>
<6DE4E50D-C195-4731-BF1C-C1134B69FA99@gmail.com>
<CAKFQuwbdScCczkpNevikNOGC=XVT6Lch_z1TOtAA_csELOL8hw@mail.gmail.com>
<3A66BB3E-8230-45D7-ACF0-122B725957BF@gmail.com>
<CAHGQGwFSxdXh-LsSTj+EE6VhJm6XjpgiH42kUsUDxgXViFn-Cg@mail.gmail.com>
> On Mar 3, 2026, at 08:28, Fujii Masao <masao.fujii@gmail.com> wrote:
>
> On Tue, Mar 3, 2026 at 8:42 AM Chao Li <li.evan.chao@gmail.com> wrote:
>>
>>
>>
>>> On Feb 28, 2026, at 09:21, David G. Johnston <david.g.johnston@gmail.com> wrote:
>>>
>>> On Fri, Feb 27, 2026 at 5:12 PM Chao Li <li.evan.chao@gmail.com> wrote:
>>>
>>> PFA v3.
>
> Thanks for updating the patch! LGTM
>
> One more comment: the handling of empty-string comments exists in both
> CreateComments() and CreateSharedComments(). For better test coverage,
> how about adding also the regression test to check that COMMENT with
> empty-string works as expected for shared objects such as roles?
>
Sure. CreateSharedComments() handles database, tablespace and role, so as you suggested, I added tests for role in v4.
> From: zhangqiang <zhang_qiang81@163.com>
>
> Hi hackers,I have verified that using an empty string does indeed delete comments. I agree this patch content enables users to better understand how the database program handles empty strings when using the COMMENT ON command in documentation, thereby improving the user experience.I think it's a good patch.
>
Thanks for your review. Sounds good.
PFA v4:
* Add tests that use NULL and ‘’ to remove comments from a role object.
Best regards
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/Attachments:
[application/octet-stream] v4-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch (7.4K, ../F88CAD6A-7CD2-445D-AE79-76F3F827B296@gmail.com/2-v4-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch)
download | inline diff:
From fc703fb4f32818e6f7d3ba1fb2434e4f094bc415 Mon Sep 17 00:00:00 2001
From: "Chao Li (Evan)" <lic@highgo.com>
Date: Thu, 26 Feb 2026 13:43:24 +0800
Subject: [PATCH v4] 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.
Author: Chao Li <lic@highgo.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.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>
Discussion: https://postgr.es/m/26476097-B1C1-4BA8-AA92-0AD0B8EC7190@gmail.com
---
doc/src/sgml/ref/comment.sgml | 18 +++++++++------
src/test/regress/expected/create_index.out | 14 +++++++++++
src/test/regress/expected/create_role.out | 27 ++++++++++++++++++++++
src/test/regress/sql/create_index.sql | 4 ++++
src/test/regress/sql/create_role.sql | 7 ++++++
5 files changed, 63 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgmlindex 8d81244910b..fa71144c914 100644--- 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.outindex c743fc769cb..55538c4c41e 100644--- 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.outindex 46d4f9efe99..5d0f21820ed 100644--- 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.sqlindex eabc9623b20..82e4062a215 100644--- 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.sqlindex 4491a28a8ae..b22f9c6f50a 100644--- 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;
--
2.50.1 (Apple Git-155)
=
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: li.evan.chao@gmail.com, masao.fujii@gmail.com, david.g.johnston@gmail.com, ashutosh.bapat.oss@gmail.com, pgsql-hackers@lists.postgresql.org, zhang_qiang81@163.com
Subject: Re: doc: Clarify that empty COMMENT string removes the comment
In-Reply-To: <F88CAD6A-7CD2-445D-AE79-76F3F827B296@gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox