From: Chao Li <li.evan.chao@gmail.com>
To: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Subject: doc: Clarify that empty COMMENT string removes the comment
Date: Thu, 26 Feb 2026 14:07:14 +0800
Message-ID: <26476097-B1C1-4BA8-AA92-0AD0B8EC7190@gmail.com> (raw)
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.
From the code, it seems the behavior is intentional:
```
/* Reduce empty-string to NULL case */
if (comment != NULL && strlen(comment) == 0)
comment = 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’t 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@mail.gmail.com
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/Attachments:
[application/octet-stream] v1-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch (1.2K, ../26476097-B1C1-4BA8-AA92-0AD0B8EC7190@gmail.com/2-v1-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch)
download | inline diff:
From 469348fb023b127002dca977e93191ddf8981243 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 v1] 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.
Author: Chao Li <lic@highgo.com>
Reviewed-by:
Discussion: https://postgr.es/m/
---
doc/src/sgml/ref/comment.sgml | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgmlindex 8d81244910b..e30c7c2917e 100644--- a/doc/src/sgml/ref/comment.sgml+++ b/doc/src/sgml/ref/comment.sgml@@ -266,7 +266,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+ is treated as <literal>NULL</literal> (that is, it drops the comment).
</para>
</listitem>
</varlistentry>
--
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, pgsql-hackers@lists.postgresql.org
Subject: Re: doc: Clarify that empty COMMENT string removes the comment
In-Reply-To: <26476097-B1C1-4BA8-AA92-0AD0B8EC7190@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