Re: Table rewrite supporting functions for event triggers

On Mon, 2024-09-02 at 17:15 -0400, Greg Sabino Mullane wrote:
> While looking over the event trigger docs, I noticed that the sample code references
> the two special table rewrite functions (returning oid and reason for the rewrite),
> but the event trigger page itself does not mention them, although it does mention
> the functions available for the other types of event triggers (e.g. pg_event_trigger_ddl_commands).
> Please find attached a patch to remedy this, including the meaning of the int values
> (which, while subject to change, seems worth documenting here rather than hand-waving
> it away as func.sgml does)

I think that it would be better to add a reference to
https://www.postgresql.org/docs/16/functions-event-triggers.html#FUNCTIONS-EVENT-TRIGGER-TABLE-REWRITE
than to repeat that information.

If you feel that "The exact meaning of the codes is release dependent" is unnecessarily
vague, that sentence should be changed.

Your proposed description leaves me a bit clueless:

+ To find the OID of the table that was rewritten, use the function
+ <literal>pg_event_trigger_table_rewrite_oid()</literal>. To discover the
+ reason for the rewrite, use the function
+ <literal>pg_event_trigger_table_rewrite_reason()</literal>. This function returns
+ an integer representing a bitmap of reasons for the rewrite. The current values
+ are 1 (the table has changed persistence), 2 (a column has changed a default value),
+ 3 (a column has a new data type), and 4 (the table access method has changed).

A "bitmap of reasons" to me would mean that each reason is a bit, and if two reasons
apply at the same time, both bits are set. But that's clearly not what you mean, because
"a column has a new data type" is not the same as "the table has changed persistence"
and at the same time "a column has changed a default value".

Perhaps "a bitmap of reasons" should simply become "the reason".

Yours,
Laurenz Albe