From: Chao Li <li.evan.chao@gmail.com>
Message-Id: <F88CAD6A-7CD2-445D-AE79-76F3F827B296@gmail.com>
Content-Type: multipart/mixed;
	boundary="Apple-Mail=_A415A46C-A834-46BB-B13B-5CF719D3A7AA"
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3864.400.21\))
Subject: Re: doc: Clarify that empty COMMENT string removes the comment
Date: Tue, 3 Mar 2026 11:16:59 +0800
In-Reply-To: 
 <CAHGQGwFSxdXh-LsSTj+EE6VhJm6XjpgiH42kUsUDxgXViFn-Cg@mail.gmail.com>
Cc: "David G. Johnston" <david.g.johnston@gmail.com>,
 Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>,
 PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>,
 zhang_qiang81@163.com
To: Fujii Masao <masao.fujii@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>
Archived-At: 
 <https://www.postgresql.org/message-id/F88CAD6A-7CD2-445D-AE79-76F3F827B296%40gmail.com>
Precedence: bulk


--Apple-Mail=_A415A46C-A834-46BB-B13B-5CF719D3A7AA
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=utf-8


> On Mar 3, 2026, at 08:28, Fujii Masao <masao.fujii@gmail.com> wrote:
>=20
> On Tue, Mar 3, 2026 at 8:42=E2=80=AFAM Chao Li =
<li.evan.chao@gmail.com> wrote:
>>=20
>>=20
>>=20
>>> On Feb 28, 2026, at 09:21, David G. Johnston =
<david.g.johnston@gmail.com> wrote:
>>>=20
>>> On Fri, Feb 27, 2026 at 5:12=E2=80=AFPM Chao Li =
<li.evan.chao@gmail.com> wrote:
>>>=20
>>> PFA v3.
>=20
> Thanks for updating the patch! LGTM
>=20
> 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?
>=20

Sure. CreateSharedComments() handles database, tablespace and role, so =
as you suggested, I added tests for role in v4.

> From: zhangqiang <zhang_qiang81@163.com>
>=20
> 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.=20
>=20

Thanks for your review. Sounds good.

PFA v4:
 * Add tests that use NULL and =E2=80=98=E2=80=99 to remove comments =
from a role object.

Best regards
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/


--Apple-Mail=_A415A46C-A834-46BB-B13B-5CF719D3A7AA
Content-Disposition: attachment;
	filename=v4-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch
Content-Type: application/octet-stream;
	x-unix-mode=0644;
	name="v4-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch"
Content-Transfer-Encoding: quoted-printable

=46rom=20fc703fb4f32818e6f7d3ba1fb2434e4f094bc415=20Mon=20Sep=2017=20=
00:00:00=202001=0AFrom:=20"Chao=20Li=20(Evan)"=20<lic@highgo.com>=0A=
Date:=20Thu,=2026=20Feb=202026=2013:43:24=20+0800=0ASubject:=20[PATCH=20=
v4]=20doc:=20Clarify=20that=20empty=20COMMENT=20string=20removes=20the=20=
comment=0A=0AClarify=20the=20documentation=20of=20COMMENT=20ON=20to=20=
state=20that=20specifying=20an=20empty=0Astring=20is=20treated=20as=20=
NULL,=20meaning=20that=20the=20comment=20is=20removed.=0A=0AThis=20makes=20=
the=20behavior=20explicit=20and=20avoids=20possible=20confusion=20about=20=
how=0Aempty=20strings=20are=20handled.=0A=0AAlso=20adds=20regress=20test=20=
cases=20that=20use=20empty=20string=20to=20remove=20a=20comment.=0A=0A=
Author:=20Chao=20Li=20<lic@highgo.com>=0AReviewed-by:=20Fujii=20Masao=20=
<masao.fujii@gmail.com>=0AReviewed-by:=20Ashutosh=20Bapat=20=
<ashutosh.bapat.oss@gmail.com>=0AReviewed-by:=20David=20G.=20Johnston=20=
<david.g.johnston@gmail.com>=0AReviewed-by:=20Shengbin=20Zhao=20=
<zshengbin91@gmail.com>=0AReviewed-by:=20Jim=20Jones=20=
<jim.jones@uni-muenster.de>=0ADiscussion:=20=
https://postgr.es/m/26476097-B1C1-4BA8-AA92-0AD0B8EC7190@gmail.com=0A---=0A=
=20doc/src/sgml/ref/comment.sgml=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
|=2018=20+++++++++------=0A=20src/test/regress/expected/create_index.out=20=
|=2014=20+++++++++++=0A=20src/test/regress/expected/create_role.out=20=20=
|=2027=20++++++++++++++++++++++=0A=20=
src/test/regress/sql/create_index.sql=20=20=20=20=20=20|=20=204=20++++=0A=
=20src/test/regress/sql/create_role.sql=20=20=20=20=20=20=20|=20=207=20=
++++++=0A=205=20files=20changed,=2063=20insertions(+),=207=20=
deletions(-)=0A=0Adiff=20--git=20a/doc/src/sgml/ref/comment.sgml=20=
b/doc/src/sgml/ref/comment.sgml=0Aindex=208d81244910b..fa71144c914=20=
100644=0A---=20a/doc/src/sgml/ref/comment.sgml=0A+++=20=
b/doc/src/sgml/ref/comment.sgml=0A@@=20-80,14=20+80,16=20@@=20COMMENT=20=
ON=0A=20=20=20<title>Description</title>=0A=20=0A=20=20=20<para>=0A-=20=20=
=20<command>COMMENT</command>=20stores=20a=20comment=20about=20a=20=
database=20object.=0A+=20=20=20<command>COMMENT</command>=20stores,=20=
replaces,=20or=20removes=20the=20comment=20on=20a=0A+=20=20=20database=20=
object.=0A=20=20=20</para>=0A=20=0A=20=20=20<para>=0A-=20=20=20Only=20=
one=20comment=20string=20is=20stored=20for=20each=20object,=20so=20to=20=
modify=20a=20comment,=0A-=20=20=20issue=20a=20new=20=
<command>COMMENT</command>=20command=20for=20the=20same=20object.=20=20=
To=20remove=20a=0A-=20=20=20comment,=20write=20<literal>NULL</literal>=20=
in=20place=20of=20the=20text=20string.=0A-=20=20=20Comments=20are=20=
automatically=20dropped=20when=20their=20object=20is=20dropped.=0A+=20=20=
=20Only=20one=20comment=20string=20is=20stored=20for=20each=20object.=20=20=
Issuing=20a=20new=0A+=20=20=20<command>COMMENT</command>=20command=20for=20=
the=20same=20object=20replaces=20the=0A+=20=20=20existing=20comment.=20=20=
Specifying=20<literal>NULL</literal>=20or=20an=20empty=0A+=20=20=20=
string=20(<literal>''</literal>)=20removes=20the=20comment.=20=20=
Comments=20are=0A+=20=20=20automatically=20dropped=20when=20their=20=
object=20is=20dropped.=0A=20=20=20</para>=0A=20=0A=20=20=20<para>=0A@@=20=
-266,7=20+268,8=20@@=20COMMENT=20ON=0A=20=20=20=20=20<term><replaceable=20=
class=3D"parameter">string_literal</replaceable></term>=0A=20=20=20=20=20=
<listitem>=0A=20=20=20=20=20=20<para>=0A-=20=20=20=20=20=20The=20new=20=
comment=20contents,=20written=20as=20a=20string=20literal.=0A+=20=20=20=20=
=20=20The=20new=20comment=20contents,=20written=20as=20a=20string=20=
literal.=20=20An=20empty=20string=0A+=20=20=20=20=20=20=
(<literal>''</literal>)=20removes=20the=20comment.=0A=20=20=20=20=20=20=
</para>=0A=20=20=20=20=20</listitem>=0A=20=20=20=20</varlistentry>=0A@@=20=
-275,7=20+278,7=20@@=20COMMENT=20ON=0A=20=20=20=20=20=
<term><literal>NULL</literal></term>=0A=20=20=20=20=20<listitem>=0A=20=20=
=20=20=20=20<para>=0A-=20=20=20=20=20=20Write=20<literal>NULL</literal>=20=
to=20drop=20the=20comment.=0A+=20=20=20=20=20=20Write=20=
<literal>NULL</literal>=20to=20remove=20the=20comment.=0A=20=20=20=20=20=20=
</para>=0A=20=20=20=20=20</listitem>=0A=20=20=20=20</varlistentry>=0A@@=20=
-362,6=20+365,7=20@@=20COMMENT=20ON=20TRANSFORM=20FOR=20hstore=20=
LANGUAGE=20plpython3u=20IS=20'Transform=20between=20hstore=0A=20COMMENT=20=
ON=20TRIGGER=20my_trigger=20ON=20my_table=20IS=20'Used=20for=20RI';=0A=20=
COMMENT=20ON=20TYPE=20complex=20IS=20'Complex=20number=20data=20type';=0A=
=20COMMENT=20ON=20VIEW=20my_view=20IS=20'View=20of=20departmental=20=
costs';=0A+COMMENT=20ON=20VIEW=20my_view=20IS=20NULL;=0A=20=
</programlisting></para>=0A=20=20</refsect1>=0A=20=0Adiff=20--git=20=
a/src/test/regress/expected/create_index.out=20=
b/src/test/regress/expected/create_index.out=0Aindex=20=
c743fc769cb..55538c4c41e=20100644=0A---=20=
a/src/test/regress/expected/create_index.out=0A+++=20=
b/src/test/regress/expected/create_index.out=0A@@=20-32,6=20+32,20=20@@=20=
COMMENT=20ON=20INDEX=20six_wrong=20IS=20'bad=20index';=0A=20ERROR:=20=20=
relation=20"six_wrong"=20does=20not=20exist=0A=20COMMENT=20ON=20INDEX=20=
six=20IS=20'good=20index';=0A=20COMMENT=20ON=20INDEX=20six=20IS=20NULL;=0A=
+SELECT=20obj_description('six'::regclass,=20'pg_class')=20IS=20NULL=20=
AS=20six_comment_is_null;=0A+=20six_comment_is_null=20=0A=
+---------------------=0A+=20t=0A+(1=20row)=0A+=0A+COMMENT=20ON=20INDEX=20=
six=20IS=20'add=20the=20comment=20back';=0A+COMMENT=20ON=20INDEX=20six=20=
IS=20'';=20--=20empty=20string=20removes=20the=20comment,=20same=20as=20=
NULL=0A+SELECT=20obj_description('six'::regclass,=20'pg_class')=20IS=20=
NULL=20AS=20six_comment_is_null;=0A+=20six_comment_is_null=20=0A=
+---------------------=0A+=20t=0A+(1=20row)=0A+=0A=20--=0A=20--=20BTREE=20=
partial=20indices=0A=20--=0Adiff=20--git=20=
a/src/test/regress/expected/create_role.out=20=
b/src/test/regress/expected/create_role.out=0Aindex=20=
46d4f9efe99..5d0f21820ed=20100644=0A---=20=
a/src/test/regress/expected/create_role.out=0A+++=20=
b/src/test/regress/expected/create_role.out=0A@@=20-102,6=20+102,33=20@@=20=
CREATE=20ROLE=20regress_rolecreator=20CREATEROLE;=0A=20CREATE=20ROLE=20=
regress_hasprivs=20CREATEROLE=20LOGIN=20INHERIT=20CONNECTION=20LIMIT=20=
5;=0A=20--=20ok,=20we=20should=20be=20able=20to=20modify=20a=20role=20we=20=
created=0A=20COMMENT=20ON=20ROLE=20regress_hasprivs=20IS=20'some=20=
comment';=0A+SELECT=20shobj_description('regress_hasprivs'::regrole,=20=
'pg_authid')=20IS=20NOT=20NULL=20AS=20has_comment;=0A+=20has_comment=20=0A=
+-------------=0A+=20t=0A+(1=20row)=0A+=0A+COMMENT=20ON=20ROLE=20=
regress_hasprivs=20IS=20NULL;=0A+SELECT=20=
shobj_description('regress_hasprivs'::regrole,=20'pg_authid')=20IS=20=
NULL=20AS=20no_comment;=0A+=20no_comment=20=0A+------------=0A+=20t=0A=
+(1=20row)=0A+=0A+COMMENT=20ON=20ROLE=20regress_hasprivs=20IS=20'add=20=
the=20comment=20back';=0A+SELECT=20=
shobj_description('regress_hasprivs'::regrole,=20'pg_authid')=20IS=20NOT=20=
NULL=20AS=20has_comment;=0A+=20has_comment=20=0A+-------------=0A+=20t=0A=
+(1=20row)=0A+=0A+COMMENT=20ON=20ROLE=20regress_hasprivs=20IS=20'';=20--=20=
empty=20string=20removes=20the=20comment,=20same=20as=20NULL=0A+SELECT=20=
shobj_description('regress_hasprivs'::regrole,=20'pg_authid')=20IS=20=
NULL=20AS=20no_comment;=0A+=20no_comment=20=0A+------------=0A+=20t=0A=
+(1=20row)=0A+=0A=20ALTER=20ROLE=20regress_hasprivs=20RENAME=20TO=20=
regress_tenant;=0A=20ALTER=20ROLE=20regress_tenant=20NOINHERIT=20NOLOGIN=20=
CONNECTION=20LIMIT=207;=0A=20--=20fail,=20we=20should=20be=20unable=20to=20=
modify=20a=20role=20we=20did=20not=20create=0Adiff=20--git=20=
a/src/test/regress/sql/create_index.sql=20=
b/src/test/regress/sql/create_index.sql=0Aindex=20=
eabc9623b20..82e4062a215=20100644=0A---=20=
a/src/test/regress/sql/create_index.sql=0A+++=20=
b/src/test/regress/sql/create_index.sql=0A@@=20-45,6=20+45,10=20@@=20=
CREATE=20INDEX=20six=20ON=20shighway=20USING=20btree=20(name=20=
text_ops);=0A=20COMMENT=20ON=20INDEX=20six_wrong=20IS=20'bad=20index';=0A=
=20COMMENT=20ON=20INDEX=20six=20IS=20'good=20index';=0A=20COMMENT=20ON=20=
INDEX=20six=20IS=20NULL;=0A+SELECT=20obj_description('six'::regclass,=20=
'pg_class')=20IS=20NULL=20AS=20six_comment_is_null;=0A+COMMENT=20ON=20=
INDEX=20six=20IS=20'add=20the=20comment=20back';=0A+COMMENT=20ON=20INDEX=20=
six=20IS=20'';=20--=20empty=20string=20removes=20the=20comment,=20same=20=
as=20NULL=0A+SELECT=20obj_description('six'::regclass,=20'pg_class')=20=
IS=20NULL=20AS=20six_comment_is_null;=0A=20=0A=20--=0A=20--=20BTREE=20=
partial=20indices=0Adiff=20--git=20=
a/src/test/regress/sql/create_role.sql=20=
b/src/test/regress/sql/create_role.sql=0Aindex=20=
4491a28a8ae..b22f9c6f50a=20100644=0A---=20=
a/src/test/regress/sql/create_role.sql=0A+++=20=
b/src/test/regress/sql/create_role.sql=0A@@=20-92,6=20+92,13=20@@=20=
CREATE=20ROLE=20regress_hasprivs=20CREATEROLE=20LOGIN=20INHERIT=20=
CONNECTION=20LIMIT=205;=0A=20=0A=20--=20ok,=20we=20should=20be=20able=20=
to=20modify=20a=20role=20we=20created=0A=20COMMENT=20ON=20ROLE=20=
regress_hasprivs=20IS=20'some=20comment';=0A+SELECT=20=
shobj_description('regress_hasprivs'::regrole,=20'pg_authid')=20IS=20NOT=20=
NULL=20AS=20has_comment;=0A+COMMENT=20ON=20ROLE=20regress_hasprivs=20IS=20=
NULL;=0A+SELECT=20shobj_description('regress_hasprivs'::regrole,=20=
'pg_authid')=20IS=20NULL=20AS=20no_comment;=0A+COMMENT=20ON=20ROLE=20=
regress_hasprivs=20IS=20'add=20the=20comment=20back';=0A+SELECT=20=
shobj_description('regress_hasprivs'::regrole,=20'pg_authid')=20IS=20NOT=20=
NULL=20AS=20has_comment;=0A+COMMENT=20ON=20ROLE=20regress_hasprivs=20IS=20=
'';=20--=20empty=20string=20removes=20the=20comment,=20same=20as=20NULL=0A=
+SELECT=20shobj_description('regress_hasprivs'::regrole,=20'pg_authid')=20=
IS=20NULL=20AS=20no_comment;=0A=20ALTER=20ROLE=20regress_hasprivs=20=
RENAME=20TO=20regress_tenant;=0A=20ALTER=20ROLE=20regress_tenant=20=
NOINHERIT=20NOLOGIN=20CONNECTION=20LIMIT=207;=0A=20=0A--=20=0A2.50.1=20=
(Apple=20Git-155)=0A=0A=

--Apple-Mail=_A415A46C-A834-46BB-B13B-5CF719D3A7AA--