doc: Expand documentation of session_replication_role

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index e4a01699e46ecdc6c7200085b54f1a018411f427..37a61a13c899bdfd7320f5ed66544e78925a2110 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -6506,8 +6506,30 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         superuser privilege and results in discarding any previously cached
         query plans.  Possible values are origin (the default),
         replica and local.
-        See  for
-        more information.
+       
+
+       
+        The intended use of this setting is that logical replication systems
+        set it to replica when they are applying replicated
+        changes.  The effect of that will be that triggers and rules (that
+        have not been altered from their default configuration) will not fire
+        on the replica.  See the  clauses
+        ENABLE TRIGGER and ENABLE RULE
+        for more information.
+       
+
+       
+        PostgreSQL treats the settings origin and
+        local the same internally.  Third-party replication
+        systems may use these two values for their internal purposes, for
+        example using local to designate a session whose
+        changes should not be replicated.
+       
+
+       
+        Since foreign keys are implemented as triggers, setting this parameter
+        to replica also disables all foreign key checks,
+        which can leave data in an inconsistent state if improperly used.
        
       
      

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 7bcf242846567f4a854e6fe0ff76bf97f561f32a..686bb2c11c5a44bde554c7f30f54c8eaadbbf0dd 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -456,14 +456,30 @@ ALTER TABLE [ IF EXISTS ] name
       requires superuser privileges; it should be done with caution since
       of course the integrity of the constraint cannot be guaranteed if the
       triggers are not executed.
+     
+
+     
       The trigger firing mechanism is also affected by the configuration
       variable . Simply enabled
-      triggers will fire when the replication role is origin
+      triggers (the default) will fire when the replication role is origin
       (the default) or local. Triggers configured as ENABLE
       REPLICA will only fire if the session is in replica
       mode, and triggers configured as ENABLE ALWAYS will
-      fire regardless of the current replication mode.
+      fire regardless of the current replication role.
+     
+
+     
+      The effect of this mechanism is that in the default configuration,
+      triggers do not fire on replicas.  This is useful because if a trigger
+      is used on the origin to propagate data between tables, then the
+      replication system will also replicate the propagated data, and the
+      trigger should not fire a second time on the replica, because that would
+      lead to duplication.  However, if a trigger is used for another purpose
+      such as creating external alerts, then it might be appropriate to set it
+      to ENABLE ALWAYS so that it is also fired on
+      replicas.
      
+
      
       This command acquires a SHARE ROW EXCLUSIVE lock.
      
@@ -481,6 +497,12 @@ ALTER TABLE [ IF EXISTS ] name
       are always applied in order to keep views working even if the current
       session is in a non-default replication role.
      
+
+     
+      The rule firing mechanism is also affected by the configuration variable
+      , analogous to triggers as
+      described above.
+