From df4f3ab51730a4cdddfead0b264d394ee4925723 Mon Sep 17 00:00:00 2001
From: Peter Geoghegan <pg@bowt.ie>
Date: Fri, 31 Mar 2023 14:02:52 -0700
Subject: Add show_data option to pg_get_wal_block_info.

Allow users to opt out of returning FPI data and block data from
pg_get_wal_block_info as an optimization.  Testing has shown that this
can make function execution over twice as fast in some cases.

When pg_get_wal_block_info is called with "show_data := false", it
always returns NULL values for its block_data and block_fpi_data bytea
output parameters.  Nothing else changes.  In particular, the function
will still return the usual per-block summary of block data/FPI space
overhead.  Use of "show_data := false" is therefore feasible with all
queries that don't specifically require these raw binary strings.

Follow-up to recent work in commit 122376f0.  There still hasn't been a
stable release with the pg_get_wal_block_info function, so no bump in
the pg_walinspect extension version.

Per suggestion from Melanie Plageman.

Author: Peter Geoghegan <pg@bowt.ie>
Discussion: https://postgr.es/m/CAAKRu_bJvbcYBRj2cN6G2xV7B7-Ja+pjTO1nEnEhRR8OXYiABA@mail.gmail.com
Discussion: https://postgr.es/m/CAH2-Wzm9shOkEDM10_+qOZkRSQhKVxwBFiehH6EHWQQRd_rDPw@mail.gmail.com
---
 doc/src/sgml/pgwalinspect.sgml | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/pgwalinspect.sgml b/doc/src/sgml/pgwalinspect.sgml
index 300ffac3744..eecb6e938b6 100644
--- a/doc/src/sgml/pgwalinspect.sgml
+++ b/doc/src/sgml/pgwalinspect.sgml
@@ -133,7 +133,7 @@ block_ref        |
 
    <varlistentry>
     <term>
-     <function>pg_get_wal_block_info(start_lsn pg_lsn, end_lsn pg_lsn) returns setof record</function>
+     <function>pg_get_wal_block_info(start_lsn pg_lsn, end_lsn pg_lsn, show_data boolean DEFAULT true) returns setof record</function>
     </term>
 
     <listitem>
@@ -209,10 +209,21 @@ block_fpi_data    |
       <para>
        The <function>pg_filenode_relation</function> function (see
        <xref linkend="functions-admin-dblocation"/>) can help you to
-       determine which block/relation was modified by each WAL record
-       during original execution
+       determine which relation was modified during original execution
       </para>
      </tip>
+     <para>
+      It is possible for clients to avoid the overhead of
+      materializing block data.  This may make function execution
+      significantly faster.  When <replaceable>show_data</replaceable>
+      is set to <literal>false</literal>, <structfield>block_data</structfield>
+      and <structfield>block_fpi_data</structfield> values are omitted
+      (that is, the <structfield>block_data</structfield> and
+      <structfield>block_fpi_data</structfield> <literal>OUT</literal>
+      arguments are <literal>NULL</literal> for all rows returned).
+      Obviously, this optimization is only feasible with queries where
+      block data isn't truly required.
+     </para>
      <para>
       The function raises an error if
       <replaceable>start_lsn</replaceable> is not available.
-- 
cgit v1.2.3