public inbox for [email protected]
help / color / mirror / Atom feedFrom: =?utf-8?B?Wml6aHVhbkxpdSBYLU1BTg==?= <[email protected]>
To: =?utf-8?B?cGdzcWwtaGFja2Vycw==?= <[email protected]>
Cc: =?utf-8?B?5oiR6Ieq5bex55qE6YKu566x?= <[email protected]>
Subject: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE
Date: Sun, 7 Jun 2026 11:28:51 +0800
Message-ID: <[email protected]> (raw)
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
view thread (3+ messages) latest in thread
reply
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: [email protected]
Cc: [email protected], [email protected]
Subject: Re: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox