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

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

Hi Kyotaro,

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

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.

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.

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.

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)
44973863@qq.com

Hello,
I have reviewed your documentation patch.

It looks good to me except that there is a missing space between 'NONE' and '(' in: "SERIALIZE NONE(or OFF),"

Include information on the cost of serializing the query's output data, that is converting it to text or binary format to send to the client. This can be a significant part of the time required for regular execution of the query, if the datatype output functions are expensive or if TOASTed values must be fetched from out-of-line storage. EXPLAIN's default behavior, SERIALIZE NONE(or OFF), does not perform these conversions. If SERIALIZE TEXT or SERIALIZE BINARY is specified, the appropriate conversions are performed, and the time spent doing so is measured (unless TIMING OFF is specified). If the BUFFERS option is also specified, then any buffer accesses involved in the conversions are counted too. In no case, however, will EXPLAIN actually send the resulting data to the client; hence network transmission costs cannot be investigated this way. Serialization may only be enabled when ANALYZE is also enabled. If SERIALIZE is written without an argument, TEXT is assumed.

Could you fix this ?

Thanks.

The new status of this patch is: Waiting on Author

On Sun, 7 Jun 2026 at 15:29, ZizhuanLiu X-MAN <44973863@qq.com> wrote:

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.

It sounds like you've assumed that every existing feature must be
documented. This is a false assumption. Plenty of things exist in
PostgreSQL that are not documented. You might be surprised to discover
that you can type "ANALYSE" (the British spelling) instead of
"ANALYZE" (the American spelling) to gather statistics on a table. Or
that you can terminate your psql session with "exit" or "quit" (only
\q is documented). The "exit" / "quit" feature was added to psql to
help people who are not used to the tool. We don't want to document
that, as we don't want that to become the default way that people use
to exit the tool.

One thing that having undocumented features gives us is a much lower
bar that the undocumented feature can one day be removed.

What value do you suppose documenting that "off" is a valid option for
EXPLAIN SERIALIZE brings to the project? In my view, it's a negative
value as it adds more words to the documents without teaching anyone
about any new behaviour.

I suggest we reject this patch and keep the documentation and code for
this exactly as it is.

David

Original
From: Pierre Forstmann <pierre.forstmann@gmail.com>
Date: 2026-08-01 23:09
To: pgsql-hackers <pgsql-hackers@lists.postgresql.org>
Cc: Zizhuan Liu <44973863@qq.com>
Subject: Re: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE
Hello,
I have reviewed your documentation patch.

It looks good to me except that there is a missing space between 'NONE' and '(' in: "SERIALIZE NONE(or OFF),"

Thank you for the detailed review.
Given mixed community feedback on this patch, I plan to collect more opinions
and make a final call on whether to move forward with this change.
Much appreciated.

Include information on the cost of serializing the query's output data, that is converting it to text or binary format to send to the client. This can be a significant part of the time required for regular execution of the query, if the datatype output functions are expensive or if TOASTed values must be fetched from out-of-line storage. EXPLAIN's default behavior, SERIALIZE NONE(or OFF), does not perform these conversions. If SERIALIZE TEXT or SERIALIZE BINARY is specified, the appropriate conversions are performed, and the time spent doing so is measured (unless TIMING OFF is specified). If the BUFFERS option is also specified, then any buffer accesses involved in the conversions are counted too. In no case, however, will EXPLAIN actually send the resulting data to the client; hence network transmission costs cannot be investigated this way. Serialization may only be enabled when ANALYZE is also enabled. If SERIALIZE is written without an argument, TEXT is assumed.

Could you fix this ?

Thanks.

The new status of this patch is: Waiting on Author

This might be a separate topic. I plan to spend time later reviewing
its logic and assessing implementation feasibility. Other interested
hackers are free to explore and implement it early.

I also have a thorny patch to resolve, this will take some time:
https://commitfest.postgresql.org/patch/7075/
Fix var_eq_const: sum selectivity of all matching MCV entries instead of stopping at first match

regards,
--
ZizhuanLiu (X-MAN) 
44973863@qq.com