Stale comments for the tuple_update/tuple_delete options parameter
Hackorum builds and tests every patch posted to the lists, not only commitfest submissions. This is Hackorum's own CI rather than the PostgreSQL project's, and it is still under testing - please report anything that looks wrong.
This thread has been committed, so CI has stopped here. Anything below is the last result it produced.
You can run a PostgreSQL built from this patch straight from Docker, with no checkout and no build:
docker run --rm -p 5432:5432 ghcr.io/hackorum-dev/postgres-patch:t253372psql -h localhost -U postgresBuilt from patchset v1 (message #1), August 11, 2026 at 10:31 AM.
Every patchset is also pushed to a branch of our PostgreSQL fork, so you can check out the same tree CI built. Without a PostgreSQL checkout:
git clone --branch t253372_1 https://github.com/hackorum-dev/postgres.gitIn a checkout you already have, add the fork once:
git remote add hackorum https://github.com/hackorum-dev/postgres.gitthen, for this patchset and every later one:
git fetch hackorum t253372_1 && git checkout t253372_1Patchset v1 (message #1) is on t253372_1
Hi,
While reading the table AM interface I noticed that the comments for the
options parameter of tuple_update() and tuple_delete() have drifted from
the code. I was planning on using this options parameter myself and got
confused by the little inconsistency initially.
db89a47115f added the parameter, documented it as recognizing no values,
and marked heap_update()'s copy pg_attribute_unused(). All of that was
accurate at the time. 28d534e2ae0 then added TABLE_UPDATE_NO_LOGICAL
and TABLE_DELETE_NO_LOGICAL and began reading the parameter, but the
earlier statements were left in place.
table_tuple_update() consequently documents options twice:
* options - bitmask of options. No values are currently recognized.
* crosscheck - if not InvalidSnapshot, also check old tuple against this
* options - These allow the caller to specify options that may change the
* behavior of the AM. The AM will ignore options that it does not support.
* TABLE_UPDATE_NO_LOGICAL -- force-disables the emitting of logical
* decoding information for the tuple.
The first copy contradicts the second, and the description of crosscheck
is stranded between them.
table_tuple_delete() has a related omission: it lists only
TABLE_DELETE_CHANGING_PARTITION, so TABLE_DELETE_NO_LOGICAL is
undocumented at the interface an out-of-tree AM author would read, even
though heap_delete() has acted on it since the same commit.
The attached patch drops the stale copy, restores the parameters to
signature order, and adds the missing delete flag. Both descriptions
now follow the wording already used for TABLE_INSERT_NO_LOGICAL, which
also explains why the flag exists -- table rewrites where
RelationIsLogicallyLogged() is not yet accurate for the new relation --
since repack.c passes all three for that same reason.
It also removes the pg_attribute_unused() marker from heap_update(),
which has read options since 28d534e2ae0.
Comments only; no behaviour change.
Thanks,
Nikhil
---
Nikhil Sontakke
PlanetScale Postgres Core Team
Hi Nikhil,
On 2026-Aug-11, Nikhil Sontakke wrote:
Hi,
While reading the table AM interface I noticed that the comments for the
options parameter of tuple_update() and tuple_delete() have drifted from
the code.
Agreed, the patch looks reasonable in an initial quick look. Will get
this pushed to 19 and master once the embargo is lifted.
Thanks
--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/