aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
authorAmit Kapila <akapila@postgresql.org>2024-03-08 08:10:45 +0530
committerAmit Kapila <akapila@postgresql.org>2024-03-08 08:10:45 +0530
commitbf279ddd1c28ce0251446ee90043a4cb96e5db0f (patch)
tree642eb01435995795793fc61cedcc66949c824f1d /doc/src
parent453c46873774219243501b8efc16b2b5a5e9d194 (diff)
downloadpostgresql-bf279ddd1c28ce0251446ee90043a4cb96e5db0f.tar.gz
postgresql-bf279ddd1c28ce0251446ee90043a4cb96e5db0f.zip
Introduce a new GUC 'standby_slot_names'.
This patch provides a way to ensure that physical standbys that are potential failover candidates have received and flushed changes before the primary server making them visible to subscribers. Doing so guarantees that the promoted standby server is not lagging behind the subscribers when a failover is necessary. The logical walsender now guarantees that all local changes are sent and flushed to the standby servers corresponding to the replication slots specified in 'standby_slot_names' before sending those changes to the subscriber. Additionally, the SQL functions pg_logical_slot_get_changes, pg_logical_slot_peek_changes and pg_replication_slot_advance are modified to ensure that they process changes for failover slots only after physical slots specified in 'standby_slot_names' have confirmed WAL receipt for those. Author: Hou Zhijie and Shveta Malik Reviewed-by: Masahiko Sawada, Peter Smith, Bertrand Drouvot, Ajin Cherian, Nisha Moond, Amit Kapila Discussion: https://postgr.es/m/514f6f2f-6833-4539-39f1-96cd1e011f23@enterprisedb.com
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/config.sgml39
-rw-r--r--doc/src/sgml/func.sgml16
-rw-r--r--doc/src/sgml/logicaldecoding.sgml12
3 files changed, 63 insertions, 4 deletions
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index b38cbd714aa..65a6e6c4086 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4559,6 +4559,45 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
</listitem>
</varlistentry>
+ <varlistentry id="guc-standby-slot-names" xreflabel="standby_slot_names">
+ <term><varname>standby_slot_names</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>standby_slot_names</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ A comma-separated list of streaming replication standby server slot names
+ that logical WAL sender processes will wait for. Logical WAL sender processes
+ will send decoded changes to plugins only after the specified replication
+ slots confirm receiving WAL. This guarantees that logical replication
+ failover slots do not consume changes until those changes are received
+ and flushed to corresponding physical standbys. If a
+ logical replication connection is meant to switch to a physical standby
+ after the standby is promoted, the physical replication slot for the
+ standby should be listed here. Note that logical replication will not
+ proceed if the slots specified in the
+ <varname>standby_slot_names</varname> do not exist or are invalidated.
+ Additionally, the replication management functions
+ <link linkend="pg-replication-slot-advance">
+ <function>pg_replication_slot_advance</function></link>,
+ <link linkend="pg-logical-slot-get-changes">
+ <function>pg_logical_slot_get_changes</function></link>, and
+ <link linkend="pg-logical-slot-peek-changes">
+ <function>pg_logical_slot_peek_changes</function></link>,
+ when used with logical failover slots, will block until all
+ physical slots specified in <varname>standby_slot_names</varname> have
+ confirmed WAL receipt.
+ </para>
+ <para>
+ The standbys corresponding to the physical replication slots in
+ <varname>standby_slot_names</varname> must configure
+ <literal>sync_replication_slots = true</literal> so they can receive
+ logical failover slot changes from the primary.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect2>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index e5fa82c1619..0bb7aeb40ec 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -28150,7 +28150,7 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
</row>
<row>
- <entry role="func_table_entry"><para role="func_signature">
+ <entry id="pg-logical-slot-get-changes" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_logical_slot_get_changes</primary>
</indexterm>
@@ -28173,11 +28173,15 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
the specified value. Note, however, that the actual number of
rows returned may be larger, since this limit is only checked after
adding the rows produced when decoding each new transaction commit.
+ If the specified slot is a logical failover slot then the function will
+ not return until all physical slots specified in
+ <link linkend="guc-standby-slot-names"><varname>standby_slot_names</varname></link>
+ have confirmed WAL receipt.
</para></entry>
</row>
<row>
- <entry role="func_table_entry"><para role="func_signature">
+ <entry id="pg-logical-slot-peek-changes" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_logical_slot_peek_changes</primary>
</indexterm>
@@ -28232,7 +28236,7 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
</row>
<row>
- <entry role="func_table_entry"><para role="func_signature">
+ <entry id="pg-replication-slot-advance" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_slot_advance</primary>
</indexterm>
@@ -28248,7 +28252,11 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
the name of the slot and the actual position that it was advanced to.
The updated slot position information is written out at the next
checkpoint if any advancing is done. So in the event of a crash, the
- slot may return to an earlier position.
+ slot may return to an earlier position. If the specified slot is a
+ logical failover slot then the function will not return until all
+ physical slots specified in
+ <link linkend="guc-standby-slot-names"><varname>standby_slot_names</varname></link>
+ have confirmed WAL receipt.
</para></entry>
</row>
diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 8f13780e743..5a15bbc580c 100644
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -384,6 +384,18 @@ postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NU
must be enabled on the standby. It is also necessary to specify a valid
<literal>dbname</literal> in the
<link linkend="guc-primary-conninfo"><varname>primary_conninfo</varname></link>.
+ It's highly recommended that the said physical replication slot is named in
+ <link linkend="guc-standby-slot-names"><varname>standby_slot_names</varname></link>
+ list on the primary, to prevent the subscriber from consuming changes
+ faster than the hot standby. Even when correctly configured, some latency
+ is expected when sending changes to logical subscribers due to the waiting
+ on slots named in
+ <link linkend="guc-standby-slot-names"><varname>standby_slot_names</varname></link>.
+ When <varname>standby_slot_names</varname> is utilized, the
+ primary server will not completely shut down until the corresponding
+ standbys, associated with the physical replication slots specified
+ in <varname>standby_slot_names</varname>, have confirmed
+ receiving the WAL up to the latest flushed position on the primary server.
</para>
<para>