doc: Expand documentation of session_replication_role

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 <literal>origin</literal> (the default),
         <literal>replica</literal> and <literal>local</literal>.
-        See <xref linkend="sql-altertable"/> for
+       </para>
-        more information.
+
+       <para>
+        The intended use of this setting is that logical replication systems
+        set it to <literal>replica</literal> 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 <xref linkend="sql-altertable"/> clauses
+        <literal>ENABLE TRIGGER</literal> and <literal>ENABLE RULE</literal>
+        for more information.
+       </para>
+
+       <para>
+        PostgreSQL treats the settings <literal>origin</literal> and
+        <literal>local</literal> the same internally.  Third-party replication
+        systems may use these two values for their internal purposes, for
+        example using <literal>local</literal> to designate a session whose
+        changes should not be replicated.
+       </para>
+
+       <para>
+        Since foreign keys are implemented as triggers, setting this parameter
+        to <literal>replica</literal> also disables all foreign key checks,
+        which can leave data in an inconsistent state if improperly used.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/alter_table.sgml

@@ -456,14 +456,30 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
       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.
+     </para>
+
+     <para>
       The trigger firing mechanism is also affected by the configuration
       variable <xref linkend="guc-session-replication-role"/>. Simply enabled
-      triggers will fire when the replication role is <quote>origin</quote>
+      triggers (the default) will fire when the replication role is <quote>origin</quote>
       (the default) or <quote>local</quote>. Triggers configured as <literal>ENABLE
       REPLICA</literal> will only fire if the session is in <quote>replica</quote>
       mode, and triggers configured as <literal>ENABLE ALWAYS</literal> will
-      fire regardless of the current replication mode.
+      fire regardless of the current replication role.
      </para>
+
+     <para>
+      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 <literal>ENABLE ALWAYS</literal> so that it is also fired on
+      replicas.
+     </para>
+
      <para>
       This command acquires a <literal>SHARE ROW EXCLUSIVE</literal> lock.
      </para>
@@ -481,6 +497,12 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
       are always applied in order to keep views working even if the current
       session is in a non-default replication role.
      </para>
+
+     <para>
+      The rule firing mechanism is also affected by the configuration variable
+      <xref linkend="guc-session-replication-role"/>, analogous to triggers as
+      described above.
+     </para>
     </listitem>
    </varlistentry>