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 a76e8ac09be798d8c852c1701b714893143d4caa..8cf4691fa41c4a6661098a9022ebe597f0b75735 100644 (file)
--- a/doc/src/sgml/event-trigger.sgml
+++ b/doc/src/sgml/event-trigger.sgml
@@ -80,6 +80,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 6ee09fc288acdccec2ed7daa62c35b4f09861887..2f95d5a2b58212f2b60cf6c562f83e97e1e08621 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -27783,8 +27783,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 c11bf2d781094888a80df28e52cbc6795fcf5a54..9338b7a27776dd45ec3c2045ff60c2f1a6c400e1 100644 (file)
--- a/src/include/commands/event_trigger.h
+++ b/src/include/commands/event_trigger.h
@@ -29,6 +29,12 @@ typedef struct EventTriggerData
    CommandTag  tag;
 } EventTriggerData;
 
+/*
+ * 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