MIME-Version: 1.0
From: Paul A Jungwirth <pj@illuminatedcomputing.com>
Date: Tue, 20 Jan 2026 10:46:01 -0800
Message-ID: 
 <CA+renyWVogpNSTug5e+PTMWmTOcj8UXsAhHuHiavsVU0rzNpUQ@mail.gmail.com>
Subject: cmax docs seem misleading
To: pgsql-docs@lists.postgresql.org
Content-Type: multipart/mixed; boundary="000000000000c3a9070648d6389d"
Archived-At: 
 <https://www.postgresql.org/message-id/CA%2BrenyWVogpNSTug5e%2BPTMWmTOcj8UXsAhHuHiavsVU0rzNpUQ%40mail.gmail.com>
Precedence: bulk

--000000000000c3a9070648d6389d
Content-Type: text/plain; charset="UTF-8"

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. For example:

[v19devel:5432][334102] regression=# create table pj (a int);
CREATE TABLE
[v19devel:5432][334102] regression=# begin; insert into pj values (1);
insert into pj values (2); commit;
BEGIN
INSERT 0 1
INSERT 0 1
COMMIT
[v19devel:5432][334102] regression=# select ctid, xmin, xmax, cmin,
cmax, * from pj;
 ctid  | xmin  | xmax | cmin | cmax | a
-------+-------+------+------+------+---
 (0,1) | 22424 |    0 |    0 |    0 | 1
 (0,2) | 22424 |    0 |    1 |    1 | 2

So here you have a non-zero cmax for a not-deleted row.

The converse isn't true either. "Or zero" hints that deleted rows
might always have a non-zero value, but 0 is also just the first
command in the transaction. (Null would be a meaningful signal, but I
assume we don't want to do that.)

As far as I can tell, it is impossible to observe cmin <> cmax. From
heap_getsysattr (access/common/heaptuple.c):

        case MinCommandIdAttributeNumber:
        case MaxCommandIdAttributeNumber:

            /*
             * cmin and cmax are now both aliases for the same field, which
             * can in fact also be a combo command id.  XXX perhaps we should
             * return the "real" cmin or cmax if possible, that is if we are
             * inside the originating transaction?
             */
            result =
CommandIdGetDatum(HeapTupleHeaderGetRawCommandId(tup->t_data));
            break;

So it looks like these system columns also don't look up combocids.

I'm not interested in changing any of this, but I think we could clean
up the docs a little. The description for cmin is questionable too:

> The command identifier (starting at zero) within the inserting transaction.

That's true if the row hasn't been deleted yet, but then we overwrite the field.

Here is a patch to make both of these fields a little clearer, I
think. It could be improved further by some glossary entries
explaining what a command id is (and a combocid). Or maybe that's too
much information? 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.

[0] https://www.postgresql.org/docs/current/ddl-system-columns.html#DDL-SYSTEM-COLUMNS-CMAX

Yours,

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

--000000000000c3a9070648d6389d
Content-Type: text/x-patch; charset="US-ASCII";
	name="v1-0001-docs-Clarify-cmin-and-cmax-system-columns.patch"
Content-Disposition: attachment;
	filename="v1-0001-docs-Clarify-cmin-and-cmax-system-columns.patch"
Content-Transfer-Encoding: base64
Content-ID: <f_mkmxvkzb0>
X-Attachment-Id: f_mkmxvkzb0

RnJvbSA1Y2ZhMDVlZTljNmYwNzU4NzViNGViOWFkNmQ2NGU4MWM5Y2JkY2JiIE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiAiUGF1bCBBLiBKdW5nd2lydGgiIDxwakBpbGx1bWluYXRlZGNv
bXB1dGluZy5jb20+CkRhdGU6IFR1ZSwgMjAgSmFuIDIwMjYgMTA6MzM6MzEgLTA4MDAKU3ViamVj
dDogW1BBVENIIHYxXSBkb2NzOiBDbGFyaWZ5IGNtaW4gYW5kIGNtYXggc3lzdGVtIGNvbHVtbnMK
ClRoZXNlIGFyZSB0d28gbmFtZXMgZm9yIHRoZSBzYW1lIHBoeXNpY2FsIGZpZWxkLiBUaGUgZG9j
cyBzdWdnZXN0ZWQgdGhhdCB0aGV5CndlcmUgZGlzdGluY3QsIGFuZCB0aGUgY21heCBkZXNjcmlw
dGlvbiB3YXMgc2ltcGx5IHdyb25nIGZvciBub3QteWV0LWRlbGV0ZWQKcm93cy4KLS0tCiBkb2Mv
c3JjL3NnbWwvZGRsLnNnbWwgfCAxMiArKysrKysrKysrLS0KIDEgZmlsZSBjaGFuZ2VkLCAxMCBp
bnNlcnRpb25zKCspLCAyIGRlbGV0aW9ucygtKQoKZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9k
ZGwuc2dtbCBiL2RvYy9zcmMvc2dtbC9kZGwuc2dtbAppbmRleCA5MDcwYWFhNWE3Yy4uN2ZkZmM4
ZGExYjggMTAwNjQ0Ci0tLSBhL2RvYy9zcmMvc2dtbC9kZGwuc2dtbAorKysgYi9kb2Mvc3JjL3Nn
bWwvZGRsLnNnbWwKQEAgLTE1MTAsNyArMTUxMCwxMCBAQCBDUkVBVEUgVEFCTEUgY2lyY2xlcyAo
CiAKICAgICAgPHBhcmE+CiAgICAgICBUaGUgY29tbWFuZCBpZGVudGlmaWVyIChzdGFydGluZyBh
dCB6ZXJvKSB3aXRoaW4gdGhlIGluc2VydGluZwotICAgICAgdHJhbnNhY3Rpb24uCisgICAgICB0
cmFuc2FjdGlvbi4gIE9uY2UgdGhlIHJvdyBoYXMgYmVlbiBkZWxldGVkLCB0aGlzIGlzIHJlcGxh
Y2VkIGJ5IHRoZQorICAgICAgaWRlbnRpZmllciBvZiB0aGUgZGVsZXRlIGNvbW1hbmQgKG9yIGEg
Y29tYm8gaWRlbnRpZmllciwgaWYgc3RpbGwgaW4gdGhlCisgICAgICBzYW1lIHRyYW5zYWN0aW9u
IGFzIHRoZSBpbnNlcnQpLiA8c3RydWN0ZmllbGQ+Y21pbjwvc3RydWN0ZmllbGQ+IGFsd2F5cwor
ICAgICAgaGFzIHRoZSBzYW1lIHZhbHVlIGFzIDxzdHJ1Y3RmaWVsZD5jbWF4PC9zdHJ1Y3RmaWVs
ZD4uCiAgICAgIDwvcGFyYT4KICAgICA8L2xpc3RpdGVtPgogICAgPC92YXJsaXN0ZW50cnk+CkBA
IC0xNTQwLDcgKzE1NDMsMTIgQEAgQ1JFQVRFIFRBQkxFIGNpcmNsZXMgKAogICAgICA8L2luZGV4
dGVybT4KIAogICAgICA8cGFyYT4KLSAgICAgIFRoZSBjb21tYW5kIGlkZW50aWZpZXIgd2l0aGlu
IHRoZSBkZWxldGluZyB0cmFuc2FjdGlvbiwgb3IgemVyby4KKyAgICAgIFRoZSBjb21tYW5kIGlk
ZW50aWZpZXIgKHN0YXJ0aW5nIGF0IHplcm8pIHdpdGhpbiB0aGUgZGVsZXRpbmcKKyAgICAgIHRy
YW5zYWN0aW9uLiAgSWYgdGhlIHJvdyBoYXMgbm90IHlldCBiZWVuIGRlbGV0ZWQsIHRoaXMgaXMg
dGhlIGlkZW50aWZpZXIKKyAgICAgIG9mIHRoZSBpbnNlcnQgY29tbWFuZC4gSWYgdGhlIHJvdyB3
YXMgaW5zZXJ0ZWQgYW5kIGRlbGV0ZWQgaW4gdGhlIHNhbWUKKyAgICAgIHRyYW5zYWN0aW9uLCBp
dCBpcyBhIGNvbWJvIGlkZW50aWZpZXIgaW5zdGVhZCwgd2hvc2UgbWVhbmluZyBpcyBwcml2YXRl
CisgICAgICB0byB0aGF0IHRyYW5zYWN0aW9uLiA8c3RydWN0ZmllbGQ+Y21heDwvc3RydWN0Zmll
bGQ+IGFsd2F5cyBoYXMgdGhlIHNhbWUKKyAgICAgIHZhbHVlIGFzIDxzdHJ1Y3RmaWVsZD5jbWlu
PC9zdHJ1Y3RmaWVsZD4uCiAgICAgIDwvcGFyYT4KICAgICA8L2xpc3RpdGVtPgogICAgPC92YXJs
aXN0ZW50cnk+Ci0tIAoyLjQ3LjMKCg==
--000000000000c3a9070648d6389d--