Date: Mon, 08 Jun 2026 11:51:04 +0900 (JST)
Message-Id: <20260608.115104.1546503424691983310.horikyota.ntt@gmail.com>
To: 44973863@qq.com
Cc: pgsql-hackers@lists.postgresql.org
Subject: Re: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE
From: Kyotaro Horiguchi <horikyota.ntt@gmail.com>
In-Reply-To: <tencent_D262F39BCF52823AA5B104DEA3AD83767705@qq.com>
References: <tencent_D262F39BCF52823AA5B104DEA3AD83767705@qq.com>
User-Agent: Mew version 6.8 on Emacs 29.4
Mime-Version: 1.0
Content-Type: Text/Plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Archived-At: 
 <https://www.postgresql.org/message-id/20260608.115104.1546503424691983310.horikyota.ntt%40gmail.com>
Precedence: bulk

At Sun, 7 Jun 2026 11:28:51 +0800, "ZizhuanLiu X-MAN" <44973863@qq.com> wrote in 
> I confirmed the equivalence between OFF and NONE via the following tests:
> ```sql
> explain (ANALYZE true, SERIALIZE off    ) select * from pg_catalog.pg_stat_lock;
> explain (ANALYZE true, SERIALIZE none) select * from pg_catalog.pg_stat_lock;
> ```
> Both statements execute identically with consistent runtime behavior.
> 
> To keep this patch minimal and focused, I leave the enum, tab completion and 
> regression tests unchanged for now. This patch simply adds a note to the 
> documentation stating that OFF is a valid alias for NONE. Any remaining 
> inconsistencies can be addressed in separate follow-up patches later.
> 
> 
> Reviews, comments and feedback are all welcome.


Personally, I'm not sure this is worth documenting.

Some enum-valued options accept boolean-style representations that are
not mentioned in the documentation. In some cases this is simply an
implementation detail, while in others it is provided as a convenience
or for consistency with existing conventions.

For example, the documentation for the enum-valued GUC parameter
synchronous_commit describes the meaningful settings as "on", "off",
"local", "remote_write", and "remote_apply". It also accepts "1" and
"0", though those are not documented. The same applies to SQL-level
options such as those used in CREATE SUBSCRIPTION WITH (...). However,
I don't think it would be particularly helpful to add "1" and "0" to
the documentation.

Coming back to SERIALIZE, I see OFF in much the same way: it seems
more like a convenience alias than a distinct option that users need
to know about. For that reason, I don't feel there is much value in
documenting it explicitly.

That said, I can see a somewhat stronger case for documenting OFF here
than for documenting boolean-style aliases such as 0 and 1. Since
SERIALIZE otherwise takes enum-style values (NONE, TEXT, and BINARY),
seeing OFF may leave readers wondering whether it has a meaning
distinct from NONE.

Even so, if we do decide to mention it, the proposed wording feels a
bit heavy to me. Something like "SERIALIZE NONE (or OFF)" would
probably be sufficient.

Regards.

-- 
Kyotaro Horiguchi
NTT Open Source Software Center