Subject: [PATCH] Docs: clarify default values of EXPLAIN BUFFERS and SERIALIZE

From: "Ryo Matsumura (Fujitsu)" <[email-masked]>
Date: Fri, 13 Mar 2026 08:38:35 +0000

Hi Hackers,

It looks like the EXPLAIN documentation is missing an explanation of the default values for the BUFFERS and SERIALIZE options.
I've attached a patch that adds this information.
While the documentation currently notes that these options are implicitly enabled when ANALYZE is specified, the default values of the parameters themselves do not appear to be documented.

Best Regards
Ryo Matsumura

---

From: Fujii Masao <[email-masked]>
Date: Fri, 13 Mar 2026 23:38:57 +0900

> While the documentation currently notes that these options are implicitly enabled when ANALYZE is specified, the default values of the parameters themselves do not appear to be documented.

+1 to adding a description of the default value.

       format, only non-zero values are printed.  Buffers information is
       automatically included when <literal>ANALYZE</literal> is used.
+      It defaults to <literal>FALSE</literal>.

How about clarifying the default depending on whether ANALYZE is used?
For example:

        When ANALYZE is used, this parameter defaults to TRUE and buffer usage
        information is included. Otherwise, it defaults to FALSE.

       argument, <literal>TEXT</literal> is assumed.
+      It defaults to <literal>FALSE</literal>.

Does SERIALIZE actually accept FALSE?

Regards,

-- 
Fujii Masao

---

From: "Ryo Matsumura (Fujitsu)" <[email-masked]>
Date: Mon, 16 Mar 2026 09:36:56 +0000

>        information is included. Otherwise, it defaults to FALSE.

Thanks for the comment. I hadn’t understood the implementation correctly.
It might also be worth clarifying that even when the BUFFERS(and WAL) is set to TRUE,
values are shown only when there is something to report as follows:

BUFFERS
       The number of blocks shown for an
       upper-level node includes those used by all its child nodes.  In text
-      format, only non-zero values are printed.  Buffers information is
-      automatically included when <literal>ANALYZE</literal> is used.
+      format, only non-zero values are printed.
+      When ANALYZE is used, this parameter defaults to <literal>TRUE</literal>
+      and buffer usage information is included.
+      Otherwise, it defaults to <literal>FALSE</literal>.
+      When the <literal>FORMAT</literal> is <literal>TEXT</literal>,
+      no output is produced unless there is something to report, even if it
+      is set to <literal>TRUE</literal>.

WAL
       In text format, only non-zero values are printed.
       This parameter may only be used when <literal>ANALYZE</literal> is also
       enabled.  It defaults to <literal>FALSE</literal>.
+      When the <literal>FORMAT</literal> is <literal>TEXT</literal>,
+      no output is produced unless there is something to report, even if it
+      is set to <literal>TRUE</literal>.

> Does SERIALIZE actually accept FALSE?

This was entirely my mistake. And the default value was already documented.

Best Regards
Ryo Matsumura

---

From: Fujii Masao <[email-masked]>
Date: Mon, 16 Mar 2026 19:30:10 +0900

> values are shown only when there is something to report as follows:

Isn't the existing description "In text format, only non-zero values
are printed." sufficient?

Regards,

-- 
Fujii Masao

---

From: Matsumura, Ryo/松村 量<[email-masked]>
Date: Tue, 17 Mar 2026 10:26:23 +0000

> are printed." sufficient?

This description is sufficient. It was a careless mistake on my part. Sorry about that.

I’ve attached a revised patch.

Best Regards
Ryo Matsumura

---

From: Fujii Masao <[email-masked]>
Date: Wed, 18 Mar 2026 00:34:26 +0900

> I’ve attached a revised patch.

Thanks for updating the patch!

Since the docs already state that buffer usage is automatically included
when ANALYZE is used, the focus here seems to be clarifying the behavior
of BUFFERS without ANALYZE. From that perspective, it might be better to
explicitly describe what happens when BUFFERS is TRUE without ANALYZE.

I've updated the patch accordingly. Patch attached. Thought?

Regards,

-- 
Fujii Masao

---

From: "Ryo Matsumura (Fujitsu)" <[email-masked]>
Date: Wed, 18 Mar 2026 10:08:57 +0000

> I've updated the patch accordingly. Patch attached. Thought?

I have no objections. Sorry for my shallow understanding.

Best Regards
Ryo Matsumura

---

From: Fujii Masao <[email-masked]>
Date: Thu, 19 Mar 2026 08:32:30 +0900

On Wed, Mar 18, 2026 at 7:09 PM Ryo Matsumura (Fujitsu)
<[email-masked]> wrote:
> I have no objections.

I've pushed the patch. Thanks!

Regards,

-- 
Fujii Masao