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
- more information.
+ </para>
+
+ <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>
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>
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>