public inbox for [email protected]help / color / mirror / Atom feed
[PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE 3+ messages / 2 participants [nested] [flat]
* [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE @ 2026-06-07 03:28 =?utf-8?B?Wml6aHVhbkxpdSBYLU1BTg==?= <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: =?utf-8?B?Wml6aHVhbkxpdSBYLU1BTg==?= @ 2026-06-07 03:28 UTC (permalink / raw) To: =?utf-8?B?cGdzcWwtaGFja2Vycw==?= <[email protected]>; +Cc: =?utf-8?B?5oiR6Ieq5bex55qE6YKu566x?= <[email protected]> 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 protected] Attachments: [application/octet-stream] v1-0001-DOCS-Mention-OFF-as-an-alias-for-EXPLAIN-SERIALIZ.patch (1.1K, 2-v1-0001-DOCS-Mention-OFF-as-an-alias-for-EXPLAIN-SERIALIZ.patch) download | inline diff: From dac015cc07755aa0b2f2d98e015e3a70fe0f1bff Mon Sep 17 00:00:00 2001 From: "ZizhuanLiu(X-MAN)" <[email protected]> Date: Sun, 7 Jun 2026 10:47:07 +0800 Subject: [PATCH v1] DOCS:Mention OFF as an alias for EXPLAIN SERIALIZE NONE --- doc/src/sgml/ref/explain.sgml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index e95e190..9d6ff28 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -223,7 +223,8 @@ ROLLBACK; expensive or if <acronym>TOAST</acronym>ed values must be fetched from out-of-line storage. <command>EXPLAIN</command>'s default behavior, <literal>SERIALIZE NONE</literal>, does not perform these - conversions. If <literal>SERIALIZE TEXT</literal> + conversions. <literal>OFF</literal> is accepted as an alias for + <literal>NONE</literal>. If <literal>SERIALIZE TEXT</literal> or <literal>SERIALIZE BINARY</literal> is specified, the appropriate conversions are performed, and the time spent doing so is measured (unless <literal>TIMING OFF</literal> is specified). If -- 2.43.0 [application/octet-stream] sql-explain.html (24.2K, 3-sql-explain.html) download ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE @ 2026-06-08 02:51 Kyotaro Horiguchi <[email protected]> parent: =?utf-8?B?Wml6aHVhbkxpdSBYLU1BTg==?= <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: Kyotaro Horiguchi @ 2026-06-08 02:51 UTC (permalink / raw) To: [email protected]; +Cc: [email protected] At Sun, 7 Jun 2026 11:28:51 +0800, "ZizhuanLiu X-MAN" <[email protected]> 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 ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE @ 2026-06-08 15:31 =?utf-8?B?Wml6aHVhbkxpdSBYLU1BTg==?= <[email protected]> parent: Kyotaro Horiguchi <[email protected]> 0 siblings, 0 replies; 3+ messages in thread From: =?utf-8?B?Wml6aHVhbkxpdSBYLU1BTg==?= @ 2026-06-08 15:31 UTC (permalink / raw) To: =?utf-8?B?S3lvdGFybyBIb3JpZ3VjaGk=?= <[email protected]>; +Cc: =?utf-8?B?cGdzcWwtaGFja2Vycw==?= <[email protected]>; =?utf-8?B?5oiR6Ieq5bex55qE6YKu566x?= <[email protected]> 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) [email protected] Attachments: [application/octet-stream] v2-0001-DOCS-Mention-OFF-as-an-alias-for-EXPLAIN-SERIALIZ.patch (1.2K, 2-v2-0001-DOCS-Mention-OFF-as-an-alias-for-EXPLAIN-SERIALIZ.patch) download | inline diff: From 08ab0cc42c9dea209c3285111daeb7bfe348be67 Mon Sep 17 00:00:00 2001 From: "ZizhuanLiu(X-MAN)" <[email protected]> Date: Mon, 8 Jun 2026 23:08:23 +0800 Subject: [PATCH v2] DOCS:Mention OFF as an alias for EXPLAIN SERIALIZE NONE --- doc/src/sgml/ref/explain.sgml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index e95e190..5beefe8 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -222,8 +222,8 @@ ROLLBACK; execution of the query, if the datatype output functions are expensive or if <acronym>TOAST</acronym>ed values must be fetched from out-of-line storage. <command>EXPLAIN</command>'s default - behavior, <literal>SERIALIZE NONE</literal>, does not perform these - conversions. If <literal>SERIALIZE TEXT</literal> + behavior, <literal>SERIALIZE NONE</literal>(or <literal>OFF</literal>), + does not perform these conversions. If <literal>SERIALIZE TEXT</literal> or <literal>SERIALIZE BINARY</literal> is specified, the appropriate conversions are performed, and the time spent doing so is measured (unless <literal>TIMING OFF</literal> is specified). If -- 2.43.0 [application/octet-stream] sql-explain.html (24.1K, 3-sql-explain.html) download [application/octet-stream] EXPLAIN.7 (17.8K, 4-EXPLAIN.7) download ^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2026-06-08 15:31 UTC | newest] Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-06-07 03:28 [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE =?utf-8?B?Wml6aHVhbkxpdSBYLU1BTg==?= <[email protected]> 2026-06-08 02:51 ` Kyotaro Horiguchi <[email protected]> 2026-06-08 15:31 ` =?utf-8?B?Wml6aHVhbkxpdSBYLU1BTg==?= <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox