| From: | ZizhuanLiu X-MAN <44973863(at)qq(dot)com> |
|---|---|
| To: | pgsql-hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org> |
| Cc: | 我自己的邮箱 <44973863(at)qq(dot)com> |
| Subject: | [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE |
| Date: | 2026-06-07 03:28:51 |
| Message-ID: | tencent_D262F39BCF52823AA5B104DEA3AD83767705@qq.com |
| Views: | Whole Thread | Raw Message | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-hackers |
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)
44973863(at)qq(dot)com
| Attachment | Content-Type | Size |
|---|---|---|
| v1-0001-DOCS-Mention-OFF-as-an-alias-for-EXPLAIN-SERIALIZ.patch | application/octet-stream | 1.1 KB |
| sql-explain.html | application/octet-stream | 24.2 KB |
| From | Date | Subject | |
|---|---|---|---|
| Previous Message | Chao Li | 2026-06-07 03:03:49 | Re: Fix bug of UPDATE/DELETE FOR PORTION OF with inheritance tables |