Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit a063d84

Browse files
committed
doc: Expand documentation of session_replication_role
1 parent f033462 commit a063d84

File tree

2 files changed

+48
-4
lines changed

2 files changed

+48
-4
lines changed

doc/src/sgml/config.sgml

+24-2
Original file line numberDiff line numberDiff line change
@@ -6506,8 +6506,30 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
65066506
superuser privilege and results in discarding any previously cached
65076507
query plans. Possible values are <literal>origin</literal> (the default),
65086508
<literal>replica</literal> and <literal>local</literal>.
6509-
See <xref linkend="sql-altertable"/> for
6510-
more information.
6509+
</para>
6510+
6511+
<para>
6512+
The intended use of this setting is that logical replication systems
6513+
set it to <literal>replica</literal> when they are applying replicated
6514+
changes. The effect of that will be that triggers and rules (that
6515+
have not been altered from their default configuration) will not fire
6516+
on the replica. See the <xref linkend="sql-altertable"/> clauses
6517+
<literal>ENABLE TRIGGER</literal> and <literal>ENABLE RULE</literal>
6518+
for more information.
6519+
</para>
6520+
6521+
<para>
6522+
PostgreSQL treats the settings <literal>origin</literal> and
6523+
<literal>local</literal> the same internally. Third-party replication
6524+
systems may use these two values for their internal purposes, for
6525+
example using <literal>local</literal> to designate a session whose
6526+
changes should not be replicated.
6527+
</para>
6528+
6529+
<para>
6530+
Since foreign keys are implemented as triggers, setting this parameter
6531+
to <literal>replica</literal> also disables all foreign key checks,
6532+
which can leave data in an inconsistent state if improperly used.
65116533
</para>
65126534
</listitem>
65136535
</varlistentry>

doc/src/sgml/ref/alter_table.sgml

+24-2
Original file line numberDiff line numberDiff line change
@@ -456,14 +456,30 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
456456
requires superuser privileges; it should be done with caution since
457457
of course the integrity of the constraint cannot be guaranteed if the
458458
triggers are not executed.
459+
</para>
460+
461+
<para>
459462
The trigger firing mechanism is also affected by the configuration
460463
variable <xref linkend="guc-session-replication-role"/>. Simply enabled
461-
triggers will fire when the replication role is <quote>origin</quote>
464+
triggers (the default) will fire when the replication role is <quote>origin</quote>
462465
(the default) or <quote>local</quote>. Triggers configured as <literal>ENABLE
463466
REPLICA</literal> will only fire if the session is in <quote>replica</quote>
464467
mode, and triggers configured as <literal>ENABLE ALWAYS</literal> will
465-
fire regardless of the current replication mode.
468+
fire regardless of the current replication role.
469+
</para>
470+
471+
<para>
472+
The effect of this mechanism is that in the default configuration,
473+
triggers do not fire on replicas. This is useful because if a trigger
474+
is used on the origin to propagate data between tables, then the
475+
replication system will also replicate the propagated data, and the
476+
trigger should not fire a second time on the replica, because that would
477+
lead to duplication. However, if a trigger is used for another purpose
478+
such as creating external alerts, then it might be appropriate to set it
479+
to <literal>ENABLE ALWAYS</literal> so that it is also fired on
480+
replicas.
466481
</para>
482+
467483
<para>
468484
This command acquires a <literal>SHARE ROW EXCLUSIVE</literal> lock.
469485
</para>
@@ -481,6 +497,12 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
481497
are always applied in order to keep views working even if the current
482498
session is in a non-default replication role.
483499
</para>
500+
501+
<para>
502+
The rule firing mechanism is also affected by the configuration variable
503+
<xref linkend="guc-session-replication-role"/>, analogous to triggers as
504+
described above.
505+
</para>
484506
</listitem>
485507
</varlistentry>
486508

0 commit comments

Comments
 (0)