Subject: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE

From: "ZizhuanLiu X-MAN" <[email-masked]>
Date: Sun, 7 Jun 2026 11:28:51 +0800

Hi hackers,

While reviewing CommitFest patch 6740, I noticed inconsistencies across the 
codebase regarding valid values for the EXPLAIN SERIALIZE option.

This is a documentation-only patch targeting the SERIALIZE option, 
which was originally added in CommitFest 2024-03 (patch #4852).

The parsing logic in `ParseExplainOptionList()` (explain_state.c) accepts 
the keyword `OFF` and treats it as an exact alias for `NONE`. This behavior 
is functional but currently undocumented.

I have identified four related inconsistencies:
1. The documented syntax only lists NONE | TEXT | BINARY
2. The `ExplainSerializeOption` enum in explain_state.h defines only three entries
3. psql tab completion only suggests NONE, TEXT and BINARY
4. Regression tests in explain.sql do not cover the OFF keyword

I initially thought about removing the OFF parsing logic to align all components. 
However, to preserve backward compatibility for existing queries and scripts, 
I chose not to make this code change.

This patch has been built, and the generated HTML documentation has been fully verified.

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.

regards,
--
ZizhuanLiu (X-MAN) 
[email-masked]

---

From: Kyotaro Horiguchi <[email-masked]>
Date: Mon, 08 Jun 2026 11:51:04 +0900 (JST)

At Sun, 7 Jun 2026 11:28:51 +0800, "ZizhuanLiu X-MAN" <[email-masked]> wrote in 
> 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

---

From: "ZizhuanLiu X-MAN" <[email-masked]>
Date: Mon, 8 Jun 2026 23:31:21 +0800

Hi Kyotaro,

Thanks a lot for your careful review and clear explanation of the community convention.

>or for consistency with existing conventions.
    Following your lead, I checked guc_tables.c and its corresponding official 
documentation for GUC parameters, and noticed that OFF is commonly 
documented as a valid enum/configuration option in many existing entries.

>bit heavy to me. Something like "SERIALIZE NONE (or OFF)" would
    So I fully agree with your suggestion to use minimal wording rather than
a separate explanatory paragraph. I will revise the docs to simply write
NONE (or OFF)  as you proposed.

The patch has been recompiled, and the updated HTML documentation 
and man 7 manual pages have been regenerated and verified.

regards,
--
ZizhuanLiu (X-MAN) 
[email-masked]