Hey team, I was going through the docs trying to understand the requirements of a Heap-Only Tuple update for a situation I faced where an update query was marking all columns as modified and thus was causing write amplification.The official docs led me to believe that because a new tuple was being created from this update, HOT update would never occur, but checking the source code, I came across this passage from the README.HOT <https://github.com/postgres/postgres/blob/a9afa021e95f2b0ffaaf26f3a27e685f634f4ac9/src/backend/access/heap/README.HOT#L141> which details that there is runtime comparison logic "The requirement for doing a HOT update is that none of the indexed columns are changed. This is checked at execution time by comparing the binary representation of the old and new values."
The official docs contain the first half: "The update does not modify any columns referenced by the table's indexes, not including summarizing indexes. The only summarizing index method in the core PostgreSQL distribution is BRIN <https://www.postgresql.org/docs/current/brin.html>.", I suggest continuing it with "At runtime, a binary comparison checks old and new values to determine if a change has occurred in the indexed values" as well. I have attached a patch containing the suggested change. Thanks!
From 72d1de187e48ba1c3a807048152848072feb0eed Mon Sep 17 00:00:00 2001 From: brandtall <[email protected]> Date: Mon, 2 Feb 2026 21:00:07 +0400 Subject: [PATCH] Clarify HOT update runtime check documentation --- doc/src/sgml/storage.sgml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml index 02ddfda834a..d8dc63a4558 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -1104,7 +1104,9 @@ data. Empty in ordinary tables.</entry> The update does not modify any columns referenced by the table's indexes, not including summarizing indexes. The only summarizing index method in the core <productname>PostgreSQL</productname> distribution is <link - linkend="brin">BRIN</link>. + linkend="brin">BRIN</link>. At runtime, a binary comparison checks old + and new values to determine if a change has occurred in the indexed + values. </para> </listitem> <listitem> -- 2.52.0
