mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Expand documentation of session_replication_role

Browse Source
This commit is contained in:
Peter Eisentraut 2018-01-18 09:34:51 -05:00
parent f033462d8f
commit a063d842f8
2 changed files with 48 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/src/sgml/config.sgml
View File

@ -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
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>

26
doc/src/sgml/ref/alter_table.sgml
View File

@ -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>