Subject: [PATCH] updates to docs about HOT updates for BRIN

From: Elizabeth Christensen <[email-masked]>
Date: Mon, 26 Feb 2024 14:29:37 -0600

Hello,

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/[email-masked]>,
committed 19d8e2308b.

Thanks,
Elizabeth Christensen

---

From: Stephen Frost <[email-masked]>
Date: Mon, 26 Feb 2024 17:21:36 -0500

Greetings,

> <https://www.postgresql.org/message-id/[email-masked]>,

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?

Thanks,

Stephen

---

From: Elizabeth Christensen <[email-masked]>
Date: Mon, 26 Feb 2024 16:25:39 -0600

> On Feb 26, 2024, at 4:21 PM, Stephen Frost <[email-masked]> wrote:
> 
> Greetings,
> 

Thanks Stephen, attempt #2 here. 

Elizabeth

---

From: Stephen Frost <[email-masked]>
Date: Mon, 26 Feb 2024 18:28:42 -0500

Greetings,

> Thanks Stephen, attempt #2 here. 

Here's an updated patch which tries to improve on the wording a bit by
having it be a bit more consistent.  Would certainly welcome feedback on
it though, of course.  This is a tricky bit of language to write and
a complex optimization to explain.

Thanks!

Stephen
From bb88237d1f807572a496ff2a267ab56bef61ac8e Mon Sep 17 00:00:00 2001
From: Stephen Frost <[email-masked]>
Date: Mon, 26 Feb 2024 17:17:54 -0500
Subject: [PATCH] docs: Update HOT update docs for 19d8e2308b

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
Reviewed-By: Stephen Frost
Backpatch-through: 16
Discussion: https://postgr.es/m/CABoUFXRjisr58Ct_3VsFEdQx+fJeQTWTdJnM7XAp=[email-masked]
---
 doc/src/sgml/storage.sgml | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 3ea4e5526d..d6c53a8d25 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -1097,8 +1097,11 @@ 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 not referenced by the
+     table's indexes or are only referenced by summarizing indexes (such
+     as <acronym>BRIN</acronym>) and does not update any columns
+     referenced by the table's non-summarizing indexes, including
+     expression and partial non-summarizing indexes.
      </para>
    </listitem>
    <listitem>
@@ -1114,7 +1117,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 +1134,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-summarizing 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.34.1