summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMichael Paquier2024-10-29 06:35:01 +0000
committerMichael Paquier2024-10-29 06:35:01 +0000
commit4b7bba49e71266ec378e672a1aaa9f16823449c2 (patch)
tree27bc29ad66f64f218657ef0644738d347b3155e6
parentdda781609f977315c9ecdefc1e29f9499393aaa4 (diff)
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
-rw-r--r--doc/src/sgml/event-trigger.sgml5
-rw-r--r--doc/src/sgml/func.sgml8
-rw-r--r--src/include/commands/event_trigger.h6
3 files changed, 17 insertions, 2 deletions
diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml
index d0306390346..cfa7b3d1b2d 100644
--- a/doc/src/sgml/event-trigger.sgml
+++ b/doc/src/sgml/event-trigger.sgml
@@ -104,6 +104,11 @@
control statements are available to rewrite a table,
like <literal>CLUSTER</literal> and <literal>VACUUM</literal>,
the <literal>table_rewrite</literal> event is not triggered by them.
+ To find the OID of the table that was rewritten, use the function
+ <literal>pg_event_trigger_table_rewrite_oid()</literal> (see
+ <xref linkend="functions-event-triggers"/>). To discover the reason(s)
+ for the rewrite, use the function
+ <literal>pg_event_trigger_table_rewrite_reason()</literal>.
</para>
<para>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7be0324ac87..05f630c6a6c 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -31687,8 +31687,12 @@ CREATE EVENT TRIGGER test_event_trigger_for_drops
<returnvalue>integer</returnvalue>
</para>
<para>
- 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: <literal>1</literal>
+ (the table has changed its persistence), <literal>2</literal>
+ (default value of a column has changed), <literal>4</literal>
+ (a column has a new data type) and <literal>8</literal>
+ (the table access method has changed).
</para></entry>
</row>
</tbody>
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