From: Elizabeth Christensen <elizabeth.christensen@crunchydata.com>
Message-Id: <57759ABC-7509-49CE-9645-CC54DA441657@crunchydata.com>
Content-Type: multipart/mixed;
	boundary="Apple-Mail=_29A48BC5-B35F-4159-AF87-03CDBDB1EBC9"
Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.15\))
Subject: Re: [PATCH] updates to docs about HOT updates for BRIN
Date: Mon, 26 Feb 2024 16:25:39 -0600
In-Reply-To: <Zd0O8CqQM1ms/13i@tamriel.snowman.net>
Cc: pgsql-hackers@lists.postgresql.org
To: Stephen Frost <sfrost@snowman.net>
References: <CABoUFXRjisr58Ct_3VsFEdQx+fJeQTWTdJnM7XAp=8MUbtoa9A@mail.gmail.com>
 <Zd0O8CqQM1ms/13i@tamriel.snowman.net>
Archived-At: <https://www.postgresql.org/message-id/57759ABC-7509-49CE-9645-CC54DA441657%40crunchydata.com>
Precedence: bulk


--Apple-Mail=_29A48BC5-B35F-4159-AF87-03CDBDB1EBC9
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=us-ascii


> On Feb 26, 2024, at 4:21 PM, Stephen Frost <sfrost@snowman.net> wrote:
>=20
> Greetings,
>=20
> * Elizabeth Christensen (elizabeth.christensen@crunchydata.com) wrote:
>> I have a small documentation patch to the HOT updates page
>> <https://www.postgresql.org/docs/current/storage-hot.html>to add =
references
>> to summary (BRIN) indexes not blocking HOT updates
>> =
<https://www.postgresql.org/message-id/CAFp7QwpMRGcDAQumN7onN9HjrJ3u4X3ZRX=
dGFT0K5G2JWvnbWg@mail.gmail.com>,
>> committed 19d8e2308b.
>=20
> Sounds good to me, though the attached patch didn't want to apply, and
> it isn't immediately clear to me why, but perhaps you could try saving
> the patch from a different editor and re-sending it?
>=20
> Thanks,
>=20
> Stephen

Thanks Stephen, attempt #2 here.=20

Elizabeth


--Apple-Mail=_29A48BC5-B35F-4159-AF87-03CDBDB1EBC9
Content-Disposition: attachment;
	filename*0=v2-0001-Adding-Summary-Index-Info-to-HOT-Update-Documentatio.pat;
	filename*1=ch
Content-Type: application/octet-stream;
	x-unix-mode=0644;
	name="v2-0001-Adding-Summary-Index-Info-to-HOT-Update-Documentatio.patch"
Content-Transfer-Encoding: 7bit

From: elizabeth-christensen <elizabethannegarrett@gmail.com>
Date: Mon, 26 Feb 2024 12:09:22 -0600
Subject: [PATCH] Adding Summary Index Info to HOT Update Documentation page

Commit 19d8e2308b changed when the HOT update optimization is possible but neglected to update the Heap-Only Tuples (HOT) documentation.  This patch updates that documentation accordingly.

Author: Elizabeth Christensen
Backpatch-through: 16
Discussion: 
---
 doc/src/sgml/storage.sgml | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 3ea4e5526d..314469706e 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -1097,8 +1097,10 @@ data. Empty in ordinary tables.</entry>
   <itemizedlist>
    <listitem>
     <para>
-     The update does not modify any columns referenced by the table's
-     indexes, including expression and partial indexes.
+     The update only modifies columns which are un-indexed or are only indexed with 
+     summarizing indexes (such as BRIN) and does not update any columns referenced 
+     by the table's non-summary indexes, including expression and partial 
+     non-summary indexes.
      </para>
    </listitem>
    <listitem>
@@ -1114,7 +1116,8 @@ data. Empty in ordinary tables.</entry>
   <itemizedlist>
    <listitem>
     <para>
-     New index entries are not needed to represent updated rows.
+     New index entries are not needed to represent updated rows, however, 
+     summary indexes may still need to be updated.
     </para>
    </listitem>
    <listitem>
@@ -1130,11 +1133,10 @@ data. Empty in ordinary tables.</entry>
  </para>
 
  <para>
-  In summary, heap-only tuple updates can only be created
-  if columns used by indexes are not updated.  You can
-  increase the likelihood of sufficient page space for
-  <acronym>HOT</acronym> updates by decreasing a table's <link
-  linkend="reloption-fillfactor"><literal>fillfactor</literal></link>.
+  In summary, heap-only tuple updates can only be created if columns used by 
+  non-summary indexes are not updated. You can increase the likelihood of 
+  sufficient page space for <acronym>HOT</acronym> updates by decreasing 
+  a table's <link linkend="reloption-fillfactor"><literal>fillfactor</literal></link>.
   If you don't, <acronym>HOT</acronym> updates will still happen because
   new rows will naturally migrate to new pages and existing pages with
   sufficient free space for new row versions.  The system view <link
-- 
2.37.0


--Apple-Mail=_29A48BC5-B35F-4159-AF87-03CDBDB1EBC9--