MIME-Version: 1.0
References: 
 <CA+renyWVogpNSTug5e+PTMWmTOcj8UXsAhHuHiavsVU0rzNpUQ@mail.gmail.com>
 <1857026.1774813531@sss.pgh.pa.us>
In-Reply-To: <1857026.1774813531@sss.pgh.pa.us>
From: Paul A Jungwirth <pj@illuminatedcomputing.com>
Date: Sun, 29 Mar 2026 18:37:18 -0700
Message-ID: 
 <CA+renyVYYboiTayRRE0j1oKpeB+NjEBSUXfwgEu6O0JESSmauQ@mail.gmail.com>
Subject: Re: cmax docs seem misleading
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-docs@lists.postgresql.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: 
 <https://www.postgresql.org/message-id/CA%2BrenyVYYboiTayRRE0j1oKpeB%2BNjEBSUXfwgEu6O0JESSmauQ%40mail.gmail.com>
Precedence: bulk

On Sun, Mar 29, 2026 at 12:45=E2=80=AFPM Tom Lane <tgl@sss.pgh.pa.us> wrote=
:
>
> Paul A Jungwirth <pj@illuminatedcomputing.com> 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,

--=20
Paul              ~{:-)
pj@illuminatedcomputing.com