From: Michael Paquier Date: Tue, 29 Oct 2024 06:35:14 +0000 (+0900) Subject: doc: Add better description for rewrite functions in event triggers X-Git-Tag: REL_17_1~36 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=709ce29b16569de7ed7d013399a6249849eaae40;p=thirdparty%2Fpostgresql.git doc: Add better description for rewrite functions in event triggers There are two functions that can be used in event triggers to get more details about a rewrite happening on a relation. Both had a limited documentation: - pg_event_trigger_table_rewrite_reason() and pg_event_trigger_table_rewrite_oid() were not mentioned in the main event trigger section in the paragraph dedicated to the event table_rewrite. - pg_event_trigger_table_rewrite_reason() returns an integer which is a bitmap of the reasons why a rewrite happens. There was no explanation about the meaning of these values, forcing the reader to look at the code to find out that these are defined in event_trigger.h. While on it, let's add a comment in event_trigger.h where the AT_REWRITE_* are defined, telling to update the documentation when these values are changed. Backpatch down to 13 as a consequence of 1ad23335f36b, where this area of the documentation has been heavily reworked. Author: Greg Sabino Mullane Discussion: https://postgr.es/m/CAKAnmmL+Z6j-C8dAx1tVrnBmZJu+BSoc68WSg3sR+CVNjBCqbw@mail.gmail.com Backpatch-through: 13 --- diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml index 8e009cca050..01a7f1eb18f 100644 --- a/doc/src/sgml/event-trigger.sgml +++ b/doc/src/sgml/event-trigger.sgml @@ -99,6 +99,11 @@ control statements are available to rewrite a table, like CLUSTER and VACUUM, the table_rewrite event is not triggered by them. + To find the OID of the table that was rewritten, use the function + pg_event_trigger_table_rewrite_oid() (see + ). To discover the reason(s) + for the rewrite, use the function + pg_event_trigger_table_rewrite_reason(). diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index b24782058f4..2cd93163b75 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -31110,8 +31110,12 @@ CREATE EVENT TRIGGER test_event_trigger_for_drops integer - Returns a code explaining the reason(s) for rewriting. The exact - meaning of the codes is release dependent. + Returns a code explaining the reason(s) for rewriting. The value is + a bitmap built from the following values: 1 + (the table has changed its persistence), 2 + (default value of a column has changed), 4 + (a column has a new data type) and 8 + (the table access method has changed). diff --git a/src/include/commands/event_trigger.h b/src/include/commands/event_trigger.h index 90fc1af5f69..00cfb397584 100644 --- a/src/include/commands/event_trigger.h +++ b/src/include/commands/event_trigger.h @@ -31,6 +31,12 @@ typedef struct EventTriggerData extern PGDLLIMPORT bool event_triggers; +/* + * Reasons for relation rewrites. + * + * pg_event_trigger_table_rewrite_reason() uses these values, so make sure to + * update the documentation when changing this list. + */ #define AT_REWRITE_ALTER_PERSISTENCE 0x01 #define AT_REWRITE_DEFAULT_VAL 0x02 #define AT_REWRITE_COLUMN_REWRITE 0x04