<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>19.6. Replication</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="runtime-config-wal.html" title="19.5. Write Ahead Log" /><link rel="next" href="runtime-config-query.html" title="19.7. Query Planning" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">19.6. Replication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-wal.html" title="19.5. Write Ahead Log">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 19. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 19. Server Configuration</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 11.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="runtime-config-query.html" title="19.7. Query Planning">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="RUNTIME-CONFIG-REPLICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">19.6. Replication</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SENDER">19.6.1. Sending Servers</a></span></dt><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-MASTER">19.6.2. Master Server</a></span></dt><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY">19.6.3. Standby Servers</a></span></dt><dt><span class="sect2"><a href="runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-SUBSCRIBER">19.6.4. Subscribers</a></span></dt></dl></div><p> These settings control the behavior of the built-in <em class="firstterm">streaming replication</em> feature (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="26.2.5. Streaming Replication">Section 26.2.5</a>). Servers will be either a master or a standby server. Masters can send data, while standbys are always receivers of replicated data. When cascading replication (see <a class="xref" href="warm-standby.html#CASCADING-REPLICATION" title="26.2.7. Cascading Replication">Section 26.2.7</a>) is used, standby servers can also be senders, as well as receivers. Parameters are mainly for sending and standby servers, though some parameters have meaning only on the master server. Settings may vary across the cluster without problems if that is required. </p><div class="sect2" id="RUNTIME-CONFIG-REPLICATION-SENDER"><div class="titlepage"><div><div><h3 class="title">19.6.1. Sending Servers</h3></div></div></div><p> These parameters can be set on any server that is to send replication data to one or more standby servers. The master is always a sending server, so these parameters must always be set on the master. The role and meaning of these parameters does not change after a standby becomes the master. </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-MAX-WAL-SENDERS"><span class="term"><code class="varname">max_wal_senders</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.3.3.1.1.3" class="indexterm"></a> </span></dt><dd><p> Specifies the maximum number of concurrent connections from standby servers or streaming base backup clients (i.e., the maximum number of simultaneously running WAL sender processes). The default is 10. The value 0 means replication is disabled. WAL sender processes count towards the total number of connections, so this parameter's value must be less than <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a> minus <a class="xref" href="runtime-config-connection.html#GUC-SUPERUSER-RESERVED-CONNECTIONS">superuser_reserved_connections</a>. Abrupt streaming client disconnection might leave an orphaned connection slot behind until a timeout is reached, so this parameter should be set slightly higher than the maximum number of expected clients so disconnected clients can immediately reconnect. This parameter can only be set at server start. Also, <code class="varname">wal_level</code> must be set to <code class="literal">replica</code> or higher to allow connections from standby servers. </p></dd><dt id="GUC-MAX-REPLICATION-SLOTS"><span class="term"><code class="varname">max_replication_slots</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.3.3.2.1.3" class="indexterm"></a> </span></dt><dd><p> Specifies the maximum number of replication slots (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="26.2.6. Replication Slots">Section 26.2.6</a>) that the server can support. The default is 10. This parameter can only be set at server start. Setting it to a lower value than the number of currently existing replication slots will prevent the server from starting. Also, <code class="varname">wal_level</code> must be set to <code class="literal">replica</code> or higher to allow replication slots to be used. </p></dd><dt id="GUC-WAL-KEEP-SEGMENTS"><span class="term"><code class="varname">wal_keep_segments</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.3.3.3.1.3" class="indexterm"></a> </span></dt><dd><p> Specifies the minimum number of past log file segments kept in the <code class="filename">pg_wal</code> directory, in case a standby server needs to fetch them for streaming replication. Each segment is normally 16 megabytes. If a standby server connected to the sending server falls behind by more than <code class="varname">wal_keep_segments</code> segments, the sending server might remove a WAL segment still needed by the standby, in which case the replication connection will be terminated. Downstream connections will also eventually fail as a result. (However, the standby server can recover by fetching the segment from archive, if WAL archiving is in use.) </p><p> This sets only the minimum number of segments retained in <code class="filename">pg_wal</code>; the system might need to retain more segments for WAL archival or to recover from a checkpoint. If <code class="varname">wal_keep_segments</code> is zero (the default), the system doesn't keep any extra segments for standby purposes, so the number of old WAL segments available to standby servers is a function of the location of the previous checkpoint and status of WAL archiving. This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. </p></dd><dt id="GUC-WAL-SENDER-TIMEOUT"><span class="term"><code class="varname">wal_sender_timeout</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.3.3.4.1.3" class="indexterm"></a> </span></dt><dd><p> Terminate replication connections that are inactive longer than the specified number of milliseconds. This is useful for the sending server to detect a standby crash or network outage. A value of zero disables the timeout mechanism. This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. The default value is 60 seconds. </p></dd><dt id="GUC-TRACK-COMMIT-TIMESTAMP"><span class="term"><code class="varname">track_commit_timestamp</code> (<code class="type">boolean</code>) <a id="id-1.6.6.9.3.3.5.1.3" class="indexterm"></a> </span></dt><dd><p> Record commit time of transactions. This parameter can only be set in <code class="filename">postgresql.conf</code> file or on the server command line. The default value is <code class="literal">off</code>. </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-REPLICATION-MASTER"><div class="titlepage"><div><div><h3 class="title">19.6.2. Master Server</h3></div></div></div><p> These parameters can be set on the master/primary server that is to send replication data to one or more standby servers. Note that in addition to these parameters, <a class="xref" href="runtime-config-wal.html#GUC-WAL-LEVEL">wal_level</a> must be set appropriately on the master server, and optionally WAL archiving can be enabled as well (see <a class="xref" href="runtime-config-wal.html#RUNTIME-CONFIG-WAL-ARCHIVING" title="19.5.3. Archiving">Section 19.5.3</a>). The values of these parameters on standby servers are irrelevant, although you may wish to set them there in preparation for the possibility of a standby becoming the master. </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-SYNCHRONOUS-STANDBY-NAMES"><span class="term"><code class="varname">synchronous_standby_names</code> (<code class="type">string</code>) <a id="id-1.6.6.9.4.3.1.1.3" class="indexterm"></a> </span></dt><dd><p> Specifies a list of standby servers that can support <em class="firstterm">synchronous replication</em>, as described in <a class="xref" href="warm-standby.html#SYNCHRONOUS-REPLICATION" title="26.2.8. Synchronous Replication">Section 26.2.8</a>. There will be one or more active synchronous standbys; transactions waiting for commit will be allowed to proceed after these standby servers confirm receipt of their data. The synchronous standbys will be those whose names appear in this list, and that are both currently connected and streaming data in real-time (as shown by a state of <code class="literal">streaming</code> in the <a class="link" href="monitoring-stats.html#PG-STAT-REPLICATION-VIEW" title="Table 28.5. pg_stat_replication View"><code class="literal">pg_stat_replication</code></a> view). Specifying more than one synchronous standby can allow for very high availability and protection against data loss. </p><p> The name of a standby server for this purpose is the <code class="varname">application_name</code> setting of the standby, as set in the standby's connection information. In case of a physical replication standby, this should be set in the <code class="varname">primary_conninfo</code> setting in <code class="filename">recovery.conf</code>; the default is <code class="literal">walreceiver</code>. For logical replication, this can be set in the connection information of the subscription, and it defaults to the subscription name. For other replication stream consumers, consult their documentation. </p><p> This parameter specifies a list of standby servers using either of the following syntaxes: </p><pre class="synopsis"> [FIRST] <em class="replaceable"><code>num_sync</code></em> ( <em class="replaceable"><code>standby_name</code></em> [, ...] ) ANY <em class="replaceable"><code>num_sync</code></em> ( <em class="replaceable"><code>standby_name</code></em> [, ...] ) <em class="replaceable"><code>standby_name</code></em> [, ...] </pre><p> where <em class="replaceable"><code>num_sync</code></em> is the number of synchronous standbys that transactions need to wait for replies from, and <em class="replaceable"><code>standby_name</code></em> is the name of a standby server. <code class="literal">FIRST</code> and <code class="literal">ANY</code> specify the method to choose synchronous standbys from the listed servers. </p><p> The keyword <code class="literal">FIRST</code>, coupled with <em class="replaceable"><code>num_sync</code></em>, specifies a priority-based synchronous replication and makes transaction commits wait until their WAL records are replicated to <em class="replaceable"><code>num_sync</code></em> synchronous standbys chosen based on their priorities. For example, a setting of <code class="literal">FIRST 3 (s1, s2, s3, s4)</code> will cause each commit to wait for replies from three higher-priority standbys chosen from standby servers <code class="literal">s1</code>, <code class="literal">s2</code>, <code class="literal">s3</code> and <code class="literal">s4</code>. The standbys whose names appear earlier in the list are given higher priority and will be considered as synchronous. Other standby servers appearing later in this list represent potential synchronous standbys. If any of the current synchronous standbys disconnects for whatever reason, it will be replaced immediately with the next-highest-priority standby. The keyword <code class="literal">FIRST</code> is optional. </p><p> The keyword <code class="literal">ANY</code>, coupled with <em class="replaceable"><code>num_sync</code></em>, specifies a quorum-based synchronous replication and makes transaction commits wait until their WAL records are replicated to <span class="emphasis"><em>at least</em></span> <em class="replaceable"><code>num_sync</code></em> listed standbys. For example, a setting of <code class="literal">ANY 3 (s1, s2, s3, s4)</code> will cause each commit to proceed as soon as at least any three standbys of <code class="literal">s1</code>, <code class="literal">s2</code>, <code class="literal">s3</code> and <code class="literal">s4</code> reply. </p><p> <code class="literal">FIRST</code> and <code class="literal">ANY</code> are case-insensitive. If these keywords are used as the name of a standby server, its <em class="replaceable"><code>standby_name</code></em> must be double-quoted. </p><p> The third syntax was used before <span class="productname">PostgreSQL</span> version 9.6 and is still supported. It's the same as the first syntax with <code class="literal">FIRST</code> and <em class="replaceable"><code>num_sync</code></em> equal to 1. For example, <code class="literal">FIRST 1 (s1, s2)</code> and <code class="literal">s1, s2</code> have the same meaning: either <code class="literal">s1</code> or <code class="literal">s2</code> is chosen as a synchronous standby. </p><p> The special entry <code class="literal">*</code> matches any standby name. </p><p> There is no mechanism to enforce uniqueness of standby names. In case of duplicates one of the matching standbys will be considered as higher priority, though exactly which one is indeterminate. </p><div class="note"><h3 class="title">Note</h3><p> Each <em class="replaceable"><code>standby_name</code></em> should have the form of a valid SQL identifier, unless it is <code class="literal">*</code>. You can use double-quoting if necessary. But note that <em class="replaceable"><code>standby_name</code></em>s are compared to standby application names case-insensitively, whether double-quoted or not. </p></div><p> If no synchronous standby names are specified here, then synchronous replication is not enabled and transaction commits will not wait for replication. This is the default configuration. Even when synchronous replication is enabled, individual transactions can be configured not to wait for replication by setting the <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a> parameter to <code class="literal">local</code> or <code class="literal">off</code>. </p><p> This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. </p></dd><dt id="GUC-VACUUM-DEFER-CLEANUP-AGE"><span class="term"><code class="varname">vacuum_defer_cleanup_age</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.4.3.2.1.3" class="indexterm"></a> </span></dt><dd><p> Specifies the number of transactions by which <code class="command">VACUUM</code> and <acronym class="acronym">HOT</acronym> updates will defer cleanup of dead row versions. The default is zero transactions, meaning that dead row versions can be removed as soon as possible, that is, as soon as they are no longer visible to any open transaction. You may wish to set this to a non-zero value on a primary server that is supporting hot standby servers, as described in <a class="xref" href="hot-standby.html" title="26.5. Hot Standby">Section 26.5</a>. This allows more time for queries on the standby to complete without incurring conflicts due to early cleanup of rows. However, since the value is measured in terms of number of write transactions occurring on the primary server, it is difficult to predict just how much additional grace time will be made available to standby queries. This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. </p><p> You should also consider setting <code class="varname">hot_standby_feedback</code> on standby server(s) as an alternative to using this parameter. </p><p> This does not prevent cleanup of dead rows which have reached the age specified by <code class="varname">old_snapshot_threshold</code>. </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-REPLICATION-STANDBY"><div class="titlepage"><div><div><h3 class="title">19.6.3. Standby Servers</h3></div></div></div><p> These settings control the behavior of a standby server that is to receive replication data. Their values on the master server are irrelevant. </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-HOT-STANDBY"><span class="term"><code class="varname">hot_standby</code> (<code class="type">boolean</code>) <a id="id-1.6.6.9.5.3.1.1.3" class="indexterm"></a> </span></dt><dd><p> Specifies whether or not you can connect and run queries during recovery, as described in <a class="xref" href="hot-standby.html" title="26.5. Hot Standby">Section 26.5</a>. The default value is <code class="literal">on</code>. This parameter can only be set at server start. It only has effect during archive recovery or in standby mode. </p></dd><dt id="GUC-MAX-STANDBY-ARCHIVE-DELAY"><span class="term"><code class="varname">max_standby_archive_delay</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.5.3.2.1.3" class="indexterm"></a> </span></dt><dd><p> When Hot Standby is active, this parameter determines how long the standby server should wait before canceling standby queries that conflict with about-to-be-applied WAL entries, as described in <a class="xref" href="hot-standby.html#HOT-STANDBY-CONFLICT" title="26.5.2. Handling Query Conflicts">Section 26.5.2</a>. <code class="varname">max_standby_archive_delay</code> applies when WAL data is being read from WAL archive (and is therefore not current). The default is 30 seconds. Units are milliseconds if not specified. A value of -1 allows the standby to wait forever for conflicting queries to complete. This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. </p><p> Note that <code class="varname">max_standby_archive_delay</code> is not the same as the maximum length of time a query can run before cancellation; rather it is the maximum total time allowed to apply any one WAL segment's data. Thus, if one query has resulted in significant delay earlier in the WAL segment, subsequent conflicting queries will have much less grace time. </p></dd><dt id="GUC-MAX-STANDBY-STREAMING-DELAY"><span class="term"><code class="varname">max_standby_streaming_delay</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.5.3.3.1.3" class="indexterm"></a> </span></dt><dd><p> When Hot Standby is active, this parameter determines how long the standby server should wait before canceling standby queries that conflict with about-to-be-applied WAL entries, as described in <a class="xref" href="hot-standby.html#HOT-STANDBY-CONFLICT" title="26.5.2. Handling Query Conflicts">Section 26.5.2</a>. <code class="varname">max_standby_streaming_delay</code> applies when WAL data is being received via streaming replication. The default is 30 seconds. Units are milliseconds if not specified. A value of -1 allows the standby to wait forever for conflicting queries to complete. This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. </p><p> Note that <code class="varname">max_standby_streaming_delay</code> is not the same as the maximum length of time a query can run before cancellation; rather it is the maximum total time allowed to apply WAL data once it has been received from the primary server. Thus, if one query has resulted in significant delay, subsequent conflicting queries will have much less grace time until the standby server has caught up again. </p></dd><dt id="GUC-WAL-RECEIVER-STATUS-INTERVAL"><span class="term"><code class="varname">wal_receiver_status_interval</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.5.3.4.1.3" class="indexterm"></a> </span></dt><dd><p> Specifies the minimum frequency for the WAL receiver process on the standby to send information about replication progress to the primary or upstream standby, where it can be seen using the <a class="link" href="monitoring-stats.html#PG-STAT-REPLICATION-VIEW" title="Table 28.5. pg_stat_replication View"><code class="literal">pg_stat_replication</code></a> view. The standby will report the last write-ahead log location it has written, the last position it has flushed to disk, and the last position it has applied. This parameter's value is the maximum interval, in seconds, between reports. Updates are sent each time the write or flush positions change, or at least as often as specified by this parameter. Thus, the apply position may lag slightly behind the true position. Setting this parameter to zero disables status updates completely. This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. The default value is 10 seconds. </p></dd><dt id="GUC-HOT-STANDBY-FEEDBACK"><span class="term"><code class="varname">hot_standby_feedback</code> (<code class="type">boolean</code>) <a id="id-1.6.6.9.5.3.5.1.3" class="indexterm"></a> </span></dt><dd><p> Specifies whether or not a hot standby will send feedback to the primary or upstream standby about queries currently executing on the standby. This parameter can be used to eliminate query cancels caused by cleanup records, but can cause database bloat on the primary for some workloads. Feedback messages will not be sent more frequently than once per <code class="varname">wal_receiver_status_interval</code>. The default value is <code class="literal">off</code>. This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. </p><p> If cascaded replication is in use the feedback is passed upstream until it eventually reaches the primary. Standbys make no other use of feedback they receive other than to pass upstream. </p><p> This setting does not override the behavior of <code class="varname">old_snapshot_threshold</code> on the primary; a snapshot on the standby which exceeds the primary's age threshold can become invalid, resulting in cancellation of transactions on the standby. This is because <code class="varname">old_snapshot_threshold</code> is intended to provide an absolute limit on the time which dead rows can contribute to bloat, which would otherwise be violated because of the configuration of a standby. </p></dd><dt id="GUC-WAL-RECEIVER-TIMEOUT"><span class="term"><code class="varname">wal_receiver_timeout</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.5.3.6.1.3" class="indexterm"></a> </span></dt><dd><p> Terminate replication connections that are inactive longer than the specified number of milliseconds. This is useful for the receiving standby server to detect a primary node crash or network outage. A value of zero disables the timeout mechanism. This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. The default value is 60 seconds. </p></dd><dt id="GUC-WAL-RETRIEVE-RETRY-INTERVAL"><span class="term"><code class="varname">wal_retrieve_retry_interval</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.5.3.7.1.3" class="indexterm"></a> </span></dt><dd><p> Specify how long the standby server should wait when WAL data is not available from any sources (streaming replication, local <code class="filename">pg_wal</code> or WAL archive) before retrying to retrieve WAL data. This parameter can only be set in the <code class="filename">postgresql.conf</code> file or on the server command line. The default value is 5 seconds. Units are milliseconds if not specified. </p><p> This parameter is useful in configurations where a node in recovery needs to control the amount of time to wait for new WAL data to be available. For example, in archive recovery, it is possible to make the recovery more responsive in the detection of a new WAL log file by reducing the value of this parameter. On a system with low WAL activity, increasing it reduces the amount of requests necessary to access WAL archives, something useful for example in cloud environments where the amount of times an infrastructure is accessed is taken into account. </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-REPLICATION-SUBSCRIBER"><div class="titlepage"><div><div><h3 class="title">19.6.4. Subscribers</h3></div></div></div><p> These settings control the behavior of a logical replication subscriber. Their values on the publisher are irrelevant. </p><p> Note that <code class="varname">wal_receiver_timeout</code>, <code class="varname">wal_receiver_status_interval</code> and <code class="varname">wal_retrieve_retry_interval</code> configuration parameters affect the logical replication workers as well. </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-MAX-LOGICAL-REPLICATION-WORKERS"><span class="term"><code class="varname">max_logical_replication_workers</code> (<code class="type">int</code>) <a id="id-1.6.6.9.6.4.1.1.3" class="indexterm"></a> </span></dt><dd><p> Specifies maximum number of logical replication workers. This includes both apply workers and table synchronization workers. </p><p> Logical replication workers are taken from the pool defined by <code class="varname">max_worker_processes</code>. </p><p> The default value is 4. </p></dd><dt id="GUC-MAX-SYNC-WORKERS-PER-SUBSCRIPTION"><span class="term"><code class="varname">max_sync_workers_per_subscription</code> (<code class="type">integer</code>) <a id="id-1.6.6.9.6.4.2.1.3" class="indexterm"></a> </span></dt><dd><p> Maximum number of synchronization workers per subscription. This parameter controls the amount of parallelism of the initial data copy during the subscription initialization or when new tables are added. </p><p> Currently, there can be only one synchronization worker per table. </p><p> The synchronization workers are taken from the pool defined by <code class="varname">max_logical_replication_workers</code>. </p><p> The default value is 2. </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-wal.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-query.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">19.5. Write Ahead Log </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 19.7. Query Planning</td></tr></table></div></body></html>