public inbox for [email protected]  

help / color / mirror / Atom feed

From: Paul A Jungwirth <[email protected]>
To: Tom Lane <[email protected]>
Cc: [email protected]
Subject: Re: cmax docs seem misleading
Date: Sun, 29 Mar 2026 18:37:18 -0700
Message-ID: <CA+renyVYYboiTayRRE0j1oKpeB+NjEBSUXfwgEu6O0JESSmauQ@mail.gmail.com> (raw)
In-Reply-To: <[email protected]>
References: <CA+renyWVogpNSTug5e+PTMWmTOcj8UXsAhHuHiavsVU0rzNpUQ@mail.gmail.com>
	<[email protected]>

On Sun, Mar 29, 2026 at 12:45 PM Tom Lane <[email protected]> wrote:
>
> Paul A Jungwirth <[email protected]> writes:
> > The docs for cmax say:[0]
> >> The command identifier within the deleting transaction, or zero.
>
> > This was true once upon a time, I think. But nowadays cmax and cmin
> > are the same physical field, and the user-facing system columns don't
> > seem to be trying to interpret it.
>
> Yeah, this is a mess.  Nobody ever updated this text when we decided we
> could pack those fields into one.  I think it would be better to do
> what you suggest:
>
> > ... And maybe we should be more drastic: combine cmin &
> > cmax into one entry, and explain that they are two names for the same
> > value, which might signify the insert cid, the delete cid, or a
> > combocid.
>
> I'm not sure about good wording, but maybe like
>
>   cmin, cmax:
>
>     Originally, cmin and cmax were separate fields.  cmin was the
>     inserting command's command identifier within the inserting
>     transaction, while cmax was the updating or deleting command's
>     command identifier within the updating/deleting transaction, or
>     zero if no update or delete attempt had occurred yet.  Nowadays
>     these system columns refer to the same field and will always read
>     as the same value.  That might be the inserting command's command
>     identifier, or the deleting command's command identifier, or a
>     "combocid" that reflects both actions when those happened in the
>     same transaction.
>
> I don't know if we want to go into any more detail than that.

I agree that is plenty of detail for user-facing documentation. I
think your suggested text is a big improvement.

Yours,

-- 
Paul              ~{:-)
[email protected]

view thread (4+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: cmax docs seem misleading
  In-Reply-To: <CA+renyVYYboiTayRRE0j1oKpeB+NjEBSUXfwgEu6O0JESSmauQ@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox