diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/catalogs.sgml | 99 | ||||
| -rw-r--r-- | doc/src/sgml/config.sgml | 19 | ||||
| -rw-r--r-- | doc/src/sgml/func.sgml | 70 | ||||
| -rw-r--r-- | doc/src/sgml/high-availability.sgml | 94 | ||||
| -rw-r--r-- | doc/src/sgml/protocol.sgml | 64 | ||||
| -rw-r--r-- | doc/src/sgml/recovery-config.sgml | 16 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pg_receivexlog.sgml | 18 |
7 files changed, 366 insertions, 14 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 3f8d9bfafbb..dca24fc0705 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -234,6 +234,11 @@ </row> <row> + <entry><link linkend="catalog-pg-replication-slots"><structname>pg_replication_slots</structname></link></entry> + <entry>replication slot information</entry> + </row> + + <row> <entry><link linkend="catalog-pg-seclabel"><structname>pg_seclabel</structname></link></entry> <entry>security labels on database objects</entry> </row> @@ -5157,6 +5162,100 @@ </sect1> + <sect1 id="catalog-pg-replication-slots"> + <title><structname>pg_replication_slots</structname></title> + + <indexterm zone="catalog-pg-replication-slots"> + <primary>pg_replication_slots</primary> + </indexterm> + + <para> + The <structname>pg_replication_slots</structname> view provides a listing + of all replication slots that currently exist on the database cluster, + along with their current state. + </para> + + <para> + For more on replication slots, + see <xref linkend="streaming-replication-slots">. + </para> + + <table> + + <title><structname>pg_replication_slots</structname> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>slot_name</structfield></entry> + <entry><type>text</type></entry> + <entry></entry> + <entry>A unique, cluster-wide identifier for the replication slot</entry> + </row> + + <row> + <entry><structfield>slot_type</structfield></entry> + <entry><type>text</type></entry> + <entry></entry> + <entry>The slot type - <literal>physical</> or <literal>logical</></entry> + </row> + + <row> + <entry><structfield>datoid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.oid</literal></entry> + <entry>The oid of the database this slot is associated with, or + null. Only logical slots have an associated database.</entry> + </row> + + <row> + <entry><structfield>database</structfield></entry> + <entry><type>text</type></entry> + <entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.datname</literal></entry> + <entry>The name of the database this slot is associated with, or + null. Only logical slots have an associated database.</entry> + </row> + + <row> + <entry><structfield>active</structfield></entry> + <entry><type>boolean</type></entry> + <entry></entry> + <entry>True if this slot is currently actively being used</entry> + </row> + + <row> + <entry><structfield>xmin</structfield></entry> + <entry><type>xid</type></entry> + <entry></entry> + <entry>The oldest transaction that this slot needs the database to + retain. <literal>VACUUM</literal> cannot remove tuples deleted + by any later transaction. + </entry> + </row> + + <row> + <entry><structfield>restart_lsn</structfield></entry> + <entry><type>text</type></entry> + <entry></entry> + <entry>The address (<literal>LSN</literal>) of oldest WAL which still + might be required by the consumer of this slot and thus won't be + automatically removed during checkpoints. + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="catalog-pg-seclabel"> <title><structname>pg_seclabel</structname></title> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 1b5f831d655..000a46fabb0 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -2348,6 +2348,25 @@ include 'filename' </listitem> </varlistentry> + <varlistentry id="guc-max-replication-slots" xreflabel="max_replication_slots"> + <term><varname>max_replication_slots</varname> (<type>integer</type>)</term> + <indexterm> + <primary><varname>max_replication_slots</> configuration parameter</primary> + </indexterm> + <listitem> + <para> + Specifies the maximum number of replication slots + (see <xref linkend="streaming-replication-slots"> that the server + can support. The default is zero. This parameter can only be set at + server start. + <varname>wal_level</varname> must be set + to <literal>archive</literal> or higher to allow replication slots to + be used. Setting it to a lower value than the number of currently + existing replication slots will prevent the server from starting. + </para> + </listitem> + </varlistentry> + <varlistentry id="guc-wal-keep-segments" xreflabel="wal_keep_segments"> <term><varname>wal_keep_segments</varname> (<type>integer</type>)</term> <indexterm> diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 252539f93be..8cc65b94d10 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -16290,6 +16290,76 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </para> </sect2> + <sect2 id="functions-replication"> + <title>Replication Functions</title> + + <para> + PostgreSQL exposes a number of functions for controlling and interacting + with replication features. See <xref linkend="streaming-replication"> + and <xref linkend="streaming-replication-slots">. + </para> + + <para> + Many of these functions have equivalent commands in the replication + protocol; see <xref linkend="protocol-replication">. + </para> + + <para> + The sections <xref linkend="functions-snapshot-synchronization">, <xref + linkend="functions-recovery-control"> and <xref + linkend="functions-admin-backup"> are also relevant for replication. + </para> + + <table id="functions-replication-table"> + <title>Replication <acronym>SQL</acronym> Functions</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Function</entry> + <entry>Return Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <indexterm> + <primary>pg_create_physical_replication_slot</primary> + </indexterm> + <literal><function>pg_create_physical_replication_slot(<parameter>slotname</parameter> <type>text</type>, <parameter>plugin</parameter> <type>text</type>)</function></literal> + </entry> + <entry> + (<parameter>slotname</parameter> <type>text</type>, <parameter>xlog_position</parameter> <type>text</type>) + </entry> + <entry> + Creates a new physical replication slot named + <parameter>slotname</parameter>. Streaming changes from a physical slot + is only possible with the walsender protocol - see <xref + linkend="protocol-replication">. Corresponds to the walsender protocol + command <literal>CREATE_REPLICATION_SLOT ... PHYSICAL</literal>. + </entry> + </row> + <row> + <entry> + <indexterm> + <primary>pg_drop_replication_slot</primary> + </indexterm> + <literal><function>pg_drop_replication_slot(<parameter>slotname</parameter> <type>text</type>)</function></literal> + </entry> + <entry> + (<parameter>slotname</parameter> <type>text</type>) + </entry> + <entry> + Drops the physical or logical replication slot + named <parameter>slotname</parameter>. Same as walsender protocol + command <literal>DROP_REPLICATION_SLOT</>. + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2 id="functions-admin-dbobject"> <title>Database Object Management Functions</title> diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index e2e5ac93ab9..9d43586fe2f 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -643,7 +643,9 @@ protocol to make nodes agree on a serializable transactional order. entries in <filename>pg_hba.conf</> with the database field set to <literal>replication</>. Also ensure <varname>max_wal_senders</> is set to a sufficiently large value in the configuration file of the primary - server. + server. If replication slots will be used, + ensure that <varname>max_replication_slots</varname> is set sufficiently + high as well. </para> <para> @@ -750,13 +752,14 @@ archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r' <para> If you use streaming replication without file-based continuous - archiving, you have to set <varname>wal_keep_segments</> in the master - to a value high enough to ensure that old WAL segments are not recycled - too early, while the standby might still need them to catch up. If the - standby falls behind too much, it needs to be reinitialized from a new - base backup. If you set up a WAL archive that's accessible from the - standby, <varname>wal_keep_segments</> is not required as the standby can always - use the archive to catch up. + archiving, the server might recycle old WAL segments before the standby + has received them. If this occurs, the standby will need to be + reinitialized from a new base backup. You can avoid this by setting + <varname>wal_keep_segments</> to a value large enough to ensure that + WAL segments are not recycled too early, or by configuration a replication + slot for the standby. If you set up a WAL archive that's accessible from + the standby, these solutions are not required, since the standby can + always use the archive to catch up provided it retains enough segments. </para> <para> @@ -871,6 +874,81 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' </sect3> </sect2> + <sect2 id="streaming-replication-slots"> + <title>Replication Slots</title> + <indexterm zone="high-availability"> + <primary>Replication Slots</primary> + </indexterm> + <para> + Replication slots provide an automated way to ensure that the master does + not remove WAL segments until they have been received by all standbys, + and that the master does not remove rows which could cause a + <link linkend="hot-standby-conflict">recovery conflict</> even when the + standby is disconnected. + </para> + <para> + In lieu of using replication slots, it is possible to prevent the removal + of old WAL segments using <xref linkend="guc-wal-keep-segments">, or by + storing the segments in an archive using <xref linkend="restore-command">. + However, these methods often result in retaining more WAL segments than + required, whereas replication slots retain only the number of segments + known to be needed. An advantage of these methods is that they bound + the space requirement for <literal>pg_xlog</>; there is currently no way + to do this using replication slots. + </para> + <para> + Similarly, <varname>hot_standby_feedback</varname> + and <varname>vacuum_defer_cleanup_age</varname> provide protection against + relevant rows being removed by vacuum, but the former provides no + protection during any time period when the standby is not connected, + and the latter often needs to be set to a high value to provide adequate + protection. Replication slots overcome these disadvantages. + </para> + <sect3 id="streaming-replication-slots-manipulation"> + <title>Querying and manipulating replication slots</title> + <para> + Each replication slot has a name, which can contain lower-case letters, + numbers, and the underscore character. + </para> + <para> + Existing replication slots and their state can be seen in the + <link linkend="catalog-pg-replication-slots"><structname>pg_replication_slots</structname></link> + view. + </para> + <para> + Slots can be created and dropped either via the streaming replication + protocol (see <xref linkend="protocol-replication">) or via SQL + functions (see <xref linkend="functions-replication">). + </para> + </sect3> + <sect3 id="streaming-replication-slots-config"> + <title>Configuration Example</title> + <para> + You can create a replication slot like this: +<programlisting> +postgres=# SELECT * FROM pg_create_physical_replication_slot('node_a_slot'); + slotname | xlog_position +-------------+--------------- + node_a_slot | + +postgres=# SELECT * FROM pg_replication_slots; + slot_name | slot_type | datoid | database | active | xmin | restart_lsn +-------------+-----------+--------+----------+--------+------+------------- + node_a_slot | physical | 0 | | f | | +(1 row) +</programlisting> + To configure the standby to use this slot, <varname>primary_slotname</> + should be configured in the standby's <filename>recovery.conf</>. + Here is a simple example: +<programlisting> +standby_mode = 'on' +primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' +primary_slotname = 'node_a_slot' +</programlisting> + </para> + </sect3> + </sect2> + <sect2 id="cascading-replication"> <title>Cascading Replication</title> diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 7d99976a49c..832524e95e4 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1401,15 +1401,39 @@ The commands accepted in walsender mode are: </varlistentry> <varlistentry> - <term>START_REPLICATION <replaceable class="parameter">XXX/XXX</> TIMELINE <replaceable class="parameter">tli</></term> + <term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slotname</> <literal>PHYSICAL</literal></term> + <indexterm><primary>CREATE_REPLICATION_SLOT</primary></indexterm> + <listitem> + <para> + Create a physical replication + slot. See <xref linkend="streaming-replication-slots"> for more about + replication slots. + </para> + <variablelist> + <varlistentry> + <term><replaceable class="parameter">slotname</></term> + <listitem> + <para> + The name of the slot to create. Must be a valid replication slot + name (see <xref linkend="streaming-replication-slots-manipulation">). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>START_REPLICATION</literal> [<literal>SLOT</literal> <replaceable class="parameter">slotname</>] [<literal>PHYSICAL</literal>] <replaceable class="parameter">XXX/XXX</> <literal>TIMELINE</literal> <replaceable class="parameter">tli</></term> <listitem> <para> Instructs server to start streaming WAL, starting at - WAL position <replaceable class="parameter">XXX/XXX</> on timeline - <replaceable class="parameter">tli</>. - The server can reply with an error, e.g. if the requested section of WAL - has already been recycled. On success, server responds with a - CopyBothResponse message, and then starts to stream WAL to the frontend. + WAL position <replaceable class="parameter">XXX/XXX</>. If specified, + streaming starts on timeline <replaceable class="parameter">tli</>; + otherwise, the server's current timeline is selected. The server can + reply with an error, e.g. if the requested section of WAL has already + been recycled. On success, server responds with a CopyBothResponse + message, and then starts to stream WAL to the frontend. </para> <para> @@ -1444,6 +1468,14 @@ The commands accepted in walsender mode are: </para> <para> + If a slot's name is provided + via <replaceable class="parameter">slotname</>, it will be updated + as replication progresses so that the server knows which WAL segments - + and if <varname>hot_standby_feedback</> is on which transactions - + are still needed by the standby. + </para> + + <para> <variablelist> <varlistentry> <term> @@ -1720,6 +1752,26 @@ The commands accepted in walsender mode are: </varlistentry> <varlistentry> + <term><literal>DROP_REPLICATION_SLOT</literal> <replaceable class="parameter">slotname</></term> + <listitem> + <para> + Drops a replication slot, freeing any reserved server-side resources. If + the slot is currently in use by an active connection, this command fails. + </para> + <variablelist> + <varlistentry> + <term><replaceable class="parameter">slotname</></term> + <listitem> + <para> + The name of the slot to drop. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> <term>BASE_BACKUP [<literal>LABEL</literal> <replaceable>'label'</replaceable>] [<literal>PROGRESS</literal>] [<literal>FAST</literal>] [<literal>WAL</literal>] [<literal>NOWAIT</literal>]</term> <listitem> <para> diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml index 4a97bb7a9c4..b69ce287c8c 100644 --- a/doc/src/sgml/recovery-config.sgml +++ b/doc/src/sgml/recovery-config.sgml @@ -418,6 +418,22 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows </para> </listitem> </varlistentry> + <varlistentry id="primary-slotname" xreflabel="primary_slotname"> + <term><varname>primary_slotname</varname> (<type>string</type>)</term> + <indexterm> + <primary><varname>primary_slotname</> recovery parameter</primary> + </indexterm> + <listitem> + <para> + Optionally specifies an existing replication slot to be used when + connecting to the primary via streaming replication to control + resource removal on the upstream node + (see <xref linkend="streaming-replication-slots">). + This setting has no effect if <varname>primary_conninfo</> is not + set. + </para> + </listitem> + </varlistentry> <varlistentry id="trigger-file" xreflabel="trigger_file"> <term><varname>trigger_file</varname> (<type>string</type>)</term> <indexterm> diff --git a/doc/src/sgml/ref/pg_receivexlog.sgml b/doc/src/sgml/ref/pg_receivexlog.sgml index 19bebb62f7a..2a44af46c52 100644 --- a/doc/src/sgml/ref/pg_receivexlog.sgml +++ b/doc/src/sgml/ref/pg_receivexlog.sgml @@ -225,6 +225,24 @@ PostgreSQL documentation </para> </listitem> </varlistentry> + + <varlistentry> + <term><option>--slot</option></term> + <listitem> + <para> + Require <application>pg_receivexlog</application> to use an existing + replication slot (see <xref linkend="streaming-replication-slots">). + When this option is used, <application>pg_receivexlog</> will report + a flush position to the server, indicating when each segment has been + synchronized to disk so that the server can remove that segment if it + is not otherwise needed. When using this paramter, it is important + to make sure that <application>pg_receivexlog</> cannot become the + synchronous standby through an incautious setting of + <xref linkend="guc-synchronous-standby-names">; it does not flush + data frequently enough for this to work correctly. + </para> + </listitem> + </varlistentry> </variablelist> </para> |