From: Chao Li <li.evan.chao@gmail.com>
Content-Type: multipart/mixed;
	boundary="Apple-Mail=_084C9B93-2813-4F13-8F83-37F806DAEBC0"
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3864.400.21\))
Subject: doc: Clarify that empty COMMENT string removes the comment
Message-Id: <26476097-B1C1-4BA8-AA92-0AD0B8EC7190@gmail.com>
Date: Thu, 26 Feb 2026 14:07:14 +0800
To: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Archived-At: 
 <https://www.postgresql.org/message-id/26476097-B1C1-4BA8-AA92-0AD0B8EC7190%40gmail.com>
Precedence: bulk


--Apple-Mail=_084C9B93-2813-4F13-8F83-37F806DAEBC0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=utf-8

Hi,

While reviewing patch [1] before the holiday vacation, I noticed that =
the COMMENT ON command treats an empty string as NULL, which effectively =
removes the comment from the object. Today I also saw discussion [2], =
which mentioned the same problem.

=46rom the code, it seems the behavior is intentional:
```
    /* Reduce empty-string to NULL case */
    if (comment !=3D NULL && strlen(comment) =3D=3D 0)
        comment =3D NULL;
```

However, the documentation does not explain this behavior. It currently =
only says:
```
string_literal
   The new comment contents, written as a string literal.
```

Is it a common pattern that an empty string is treated as NULL, so that =
the documentation does not need to mention it explicitly? I don=E2=80=99t =
think so. For example, a similar command, SECURITY LABEL ON, treats an =
empty string as just an empty string.

This tiny patch enhances the documentation of COMMENT ON to clarify that =
an empty string is treated as NULL.

[1] =
https://postgr.es/m/e08cb97f-0364-4002-9cda-3c16b42e4136@uni-muenster.de
[2] =
https://postgr.es/m/CAHGQGwFJKg-aT5vajSU1v_B4K129u_SjZ3EGGHFSBhW967gcMA@ma=
il.gmail.com

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


--Apple-Mail=_084C9B93-2813-4F13-8F83-37F806DAEBC0
Content-Disposition: attachment;
	filename=v1-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch
Content-Type: application/octet-stream;
	x-unix-mode=0644;
	name="v1-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch"
Content-Transfer-Encoding: quoted-printable

=46rom=20469348fb023b127002dca977e93191ddf8981243=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=
v1]=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=0AAuthor:=20Chao=20Li=20=
<lic@highgo.com>=0AReviewed-by:=0ADiscussion:=20https://postgr.es/m/=0A=
---=0A=20doc/src/sgml/ref/comment.sgml=20|=203=20++-=0A=201=20file=20=
changed,=202=20insertions(+),=201=20deletion(-)=0A=0Adiff=20--git=20=
a/doc/src/sgml/ref/comment.sgml=20b/doc/src/sgml/ref/comment.sgml=0A=
index=208d81244910b..e30c7c2917e=20100644=0A---=20=
a/doc/src/sgml/ref/comment.sgml=0A+++=20b/doc/src/sgml/ref/comment.sgml=0A=
@@=20-266,7=20+266,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.=20An=20empty=20string=0A+=20=20=20=20=20=20is=20treated=20as=20=
<literal>NULL</literal>=20(that=20is,=20it=20drops=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=0A2.50.1=20(Apple=20Git-155)=0A=0A=

--Apple-Mail=_084C9B93-2813-4F13-8F83-37F806DAEBC0--