Re: cmax docs seem misleading

On Sun, Mar 29, 2026 at 12:45 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>
> Paul A Jungwirth <pj(at)illuminatedcomputing(dot)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,

--
Paul ~{:-)
pj(at)illuminatedcomputing(dot)com