Re: enhance wraparound warnings

On Sat, Jun 20, 2026 at 3:43 AM Nathan Bossart <nathandbossart(at)gmail(dot)com> wrote:
>
> On Sat, Jun 20, 2026 at 03:13:23AM +0900, Fujii Masao wrote:
> > The percentage is calculated as (xidWrapLimit - xid) divided by half
> > of the ID space. This represents the remaining ID space before wraparound,
> > not the percentage of IDs that are still available for use. Since
> > PostgreSQL stops assigning new XIDs/MultiXactIds at the stop limit
> > before reaching the wraparound limit, the current wording could be
> > interpreted as overstating how many IDs remain usable.
> >
> > So, how about changing the wording to match the calculation? For example:
> >
> > Approximately XX.XX% of transaction ID space remains before wraparound.
> >
> > and similarly for MultiXactIds.
>
> That seems reasonable to me, thanks.

Thanks for the review!

While reading the related log messages again, I noticed that in three of
the four XID wraparound warnings in varsup.c, the HINT still uses "XID"
while the DETAIL message uses "transaction ID". Commit edee0c621de
updated the remaining warning to use "transaction ID",
but seems to have missed the other three. Since using different terms
for the same thing in the DETAIL and HINT messages seems
inconsistent, I included the following changes in the patch. Or would
it be better to do this in a separate patch?

- errdetail("Approximately %.2f%% of transaction IDs are available for use.",
+ errdetail("Approximately %.2f%% of transaction ID space remains
before wraparound.",
(double) (xidWrapLimit - xid) / (MaxTransactionId / 2) * 100),
- errhint("To avoid XID assignment failures, execute a database-wide
VACUUM in that database.\n"
+ errhint("To avoid transaction ID assignment failures, execute a
database-wide VACUUM in that database.\n"

I also updated the comments in
src/test/modules/xid_wraparound/t/002_limits.pl, which contain
examples of the XID wraparound warnings.

Attached is the updated patch.

While making these changes, I also noticed that although commit
edee0c621de updated the runtime XID wraparound messages to use
"transaction IDs", the corresponding examples and text in
maintenance.sgml still use the older "XID" terminology. I therefore
created an additional patch (0002) to update the documentation to
match the current messages. I think this should be backpatched to v17.

Thought?

Regards,

--
Fujii Masao