Skip to content

Commit a850075

Browse files
alvherrealvherre
committed
Better document logical replication parameters
Add some cross-links between chapter "20. Server Parameters" and "31. Logical Replication" regarding the available configuration parameters, for easier navigation; and some more explanatory text too. I (Álvaro) chose to duplicate max_replication_slots in Chapter 20, because it has completely different meanings at each side of the replication link. Author: Peter Smith <smithpb2250@gmail.com> Reviewed-by: vignesh C <vignesh21@gmail.com> Reviewed-by: samay sharma <smilingsamay@gmail.com> Discussion: https://postgr.es/m/CAHut+PsESqpy7w3Y6cX98c255ZuCjvipkhKjy6hZBjOv4E6iJA@mail.gmail.com
1 parent 2af3336 commit a850075

File tree

2 files changed

+114
-38
lines changed

2 files changed

+114
-38
lines changed

‎doc/src/sgml/config.sgml

Lines changed: 50 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4156,7 +4156,13 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
41564156
<para>
41574157
These settings control the behavior of the built-in
41584158
<firstterm>streaming replication</firstterm> feature (see
4159-
<xref linkend="streaming-replication"/>). Servers will be either a
4159+
<xref linkend="streaming-replication"/>), and the built-in
4160+
<firstterm>logical replication</firstterm> feature (see
4161+
<xref linkend="logical-replication"/>).
4162+
</para>
4163+
4164+
<para>
4165+
For <emphasis>streaming replication</emphasis>, servers will be either a
41604166
primary or a standby server. Primaries can send data, while standbys
41614167
are always receivers of replicated data. When cascading replication
41624168
(see <xref linkend="cascading-replication"/>) is used, standby servers
@@ -4166,6 +4172,17 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
41664172
across the cluster without problems if that is required.
41674173
</para>
41684174

4175+
<para>
4176+
For <emphasis>logical replication</emphasis>, <firstterm>publishers</firstterm>
4177+
(servers that do <link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>)
4178+
replicate data to <firstterm>subscribers</firstterm>
4179+
(servers that do <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>).
4180+
Servers can also be publishers and subscribers at the same time. Note,
4181+
the following sections refer to publishers as "senders". For more details
4182+
about logical replication configuration settings refer to
4183+
<xref linkend="logical-replication-config"/>.
4184+
</para>
4185+
41694186
<sect2 id="runtime-config-replication-sender">
41704187
<title>Sending Servers</title>
41714188

@@ -4213,6 +4230,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
42134230
<term><varname>max_replication_slots</varname> (<type>integer</type>)
42144231
<indexterm>
42154232
<primary><varname>max_replication_slots</varname> configuration parameter</primary>
4233+
<secondary>in a sending server</secondary>
42164234
</indexterm>
42174235
</term>
42184236
<listitem>
@@ -4229,14 +4247,8 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
42294247
</para>
42304248

42314249
<para>
4232-
On the subscriber side, specifies how many replication origins (see
4233-
<xref linkend="replication-origins"/>) can be tracked simultaneously,
4234-
effectively limiting how many logical replication subscriptions can
4235-
be created on the server. Setting it to a lower value than the current
4236-
number of tracked replication origins (reflected in
4237-
<link linkend="view-pg-replication-origin-status">pg_replication_origin_status</link>,
4238-
not <link linkend="catalog-pg-replication-origin">pg_replication_origin</link>)
4239-
will prevent the server from starting.
4250+
Note that this parameter also applies on the subscriber side, but with
4251+
a different meaning.
42404252
</para>
42414253
</listitem>
42424254
</varlistentry>
@@ -4914,17 +4926,39 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
49144926
<para>
49154927
These settings control the behavior of a logical replication subscriber.
49164928
Their values on the publisher are irrelevant.
4917-
</para>
4918-
4919-
<para>
4920-
Note that <varname>wal_receiver_timeout</varname>,
4921-
<varname>wal_receiver_status_interval</varname> and
4922-
<varname>wal_retrieve_retry_interval</varname> configuration parameters
4923-
affect the logical replication workers as well.
4929+
See <xref linkend="logical-replication-config"/> for more details.
49244930
</para>
49254931

49264932
<variablelist>
49274933

4934+
<varlistentry id="guc-max-replication-slots-subscriber" xreflabel="max_replication_slots">
4935+
<term><varname>max_replication_slots</varname> (<type>integer</type>)
4936+
<indexterm>
4937+
<primary><varname>max_replication_slots</varname> configuration parameter</primary>
4938+
<secondary>in a subscriber</secondary>
4939+
</indexterm>
4940+
</term>
4941+
<listitem>
4942+
<para>
4943+
Specifies how many replication origins (see
4944+
<xref linkend="replication-origins"/>) can be tracked simultaneously,
4945+
effectively limiting how many logical replication subscriptions can
4946+
be created on the server. Setting it to a lower value than the current
4947+
number of tracked replication origins (reflected in
4948+
<link linkend="view-pg-replication-origin-status">pg_replication_origin_status</link>)
4949+
will prevent the server from starting.
4950+
<literal>max_replication_slots</literal> must be set to at least the
4951+
number of subscriptions that will be added to the subscriber, plus some
4952+
reserve for table synchronization.
4953+
</para>
4954+
4955+
<para>
4956+
Note that this parameter also applies on a sending server, but with
4957+
a different meaning.
4958+
</para>
4959+
</listitem>
4960+
</varlistentry>
4961+
49284962
<varlistentry id="guc-max-logical-replication-workers" xreflabel="max_logical_replication_workers">
49294963
<term><varname>max_logical_replication_workers</varname> (<type>integer</type>)
49304964
<indexterm>

‎doc/src/sgml/logical-replication.sgml

Lines changed: 64 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1765,31 +1765,73 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
17651765
<title>Configuration Settings</title>
17661766

17671767
<para>
1768-
Logical replication requires several configuration options to be set.
1768+
Logical replication requires several configuration options to be set. Most
1769+
options are relevant only on one side of the replication. However,
1770+
<varname>max_replication_slots</varname> is used on both the publisher and
1771+
the subscriber, but it has a different meaning for each.
17691772
</para>
17701773

1771-
<para>
1772-
On the publisher side, <varname>wal_level</varname> must be set to
1773-
<literal>logical</literal>, and <varname>max_replication_slots</varname>
1774-
must be set to at least the number of subscriptions expected to connect,
1775-
plus some reserve for table synchronization. And
1776-
<varname>max_wal_senders</varname> should be set to at least the same as
1777-
<varname>max_replication_slots</varname> plus the number of physical
1778-
replicas that are connected at the same time.
1779-
</para>
1774+
<sect2 id="logical-replication-config-publisher">
1775+
<title>Publishers</title>
1776+
1777+
<para>
1778+
<link linkend="guc-wal-level"><varname>wal_level</varname></link> must be
1779+
set to <literal>logical</literal>.
1780+
</para>
1781+
1782+
<para>
1783+
<link linkend="guc-max-replication-slots"><varname>max_replication_slots</varname></link>
1784+
must be set to at least the number of subscriptions expected to connect,
1785+
plus some reserve for table synchronization.
1786+
</para>
1787+
1788+
<para>
1789+
<link linkend="guc-max-wal-senders"><varname>max_wal_senders</varname></link>
1790+
should be set to at least the same as
1791+
<varname>max_replication_slots</varname>, plus the number of physical
1792+
replicas that are connected at the same time.
1793+
</para>
1794+
1795+
</sect2>
1796+
1797+
<sect2 id="logical-replication-config-subscriber">
1798+
<title>Subscribers</title>
1799+
1800+
<para>
1801+
<link linkend="guc-max-replication-slots-subscriber"><varname>max_replication_slots</varname></link>
1802+
must be set to at least the number of subscriptions that will be added to
1803+
the subscriber, plus some reserve for table synchronization.
1804+
</para>
1805+
1806+
<para>
1807+
<link linkend="guc-max-logical-replication-workers"><varname>max_logical_replication_workers</varname></link>
1808+
must be set to at least the number of subscriptions (for apply workers), plus
1809+
some reserve for the table synchronization workers.
1810+
</para>
1811+
1812+
<para>
1813+
<link linkend="guc-max-worker-processes"><varname>max_worker_processes</varname></link>
1814+
may need to be adjusted to accommodate for replication workers, at least
1815+
(<link linkend="guc-max-logical-replication-workers"><varname>max_logical_replication_workers</varname></link>
1816+
+ <literal>1</literal>). Note, some extensions and parallel queries also
1817+
take worker slots from <varname>max_worker_processes</varname>.
1818+
</para>
1819+
1820+
<para>
1821+
<link linkend="guc-max-sync-workers-per-subscription"><varname>max_sync_workers_per_subscription</varname></link>
1822+
controls the amount of parallelism of the initial data copy during the
1823+
subscription initialization or when new tables are added.
1824+
</para>
1825+
1826+
<para>
1827+
Logical replication workers are also affected by
1828+
<link linkend="guc-wal-receiver-timeout"><varname>wal_receiver_timeout</varname></link>,
1829+
<link linkend="guc-wal-receiver-status-interval"><varname>wal_receiver_status_interval</varname></link> and
1830+
<link linkend="guc-wal-retrieve-retry-interval"><varname>wal_receiver_retry_interval</varname></link>.
1831+
</para>
1832+
1833+
</sect2>
17801834

1781-
<para>
1782-
<varname>max_replication_slots</varname> must also be set on the subscriber.
1783-
It should be set to at least the number of subscriptions that will be added
1784-
to the subscriber, plus some reserve for table synchronization.
1785-
<varname>max_logical_replication_workers</varname> must be set to at least
1786-
the number of subscriptions, again plus some reserve for the table
1787-
synchronization. Additionally the <varname>max_worker_processes</varname>
1788-
may need to be adjusted to accommodate for replication workers, at least
1789-
(<varname>max_logical_replication_workers</varname>
1790-
+ <literal>1</literal>). Note that some extensions and parallel queries
1791-
also take worker slots from <varname>max_worker_processes</varname>.
1792-
</para>
17931835
</sect1>
17941836

17951837
<sect1 id="logical-replication-quick-setup">

0 commit comments

Comments
 (0)