From d5e4a369062d642d718ebef57c6935f849eb1121 Mon Sep 17 00:00:00 2001 From: Craig Ringer Date: Tue, 23 Feb 2016 15:31:13 +0800 Subject: [PATCH 5/8] Document failover slots --- doc/src/sgml/func.sgml | 15 +++++++++----- doc/src/sgml/high-availability.sgml | 41 +++++++++++++++++++++++++++++++++++++ doc/src/sgml/logicaldecoding.sgml | 2 +- doc/src/sgml/protocol.sgml | 19 ++++++++++++++++- 4 files changed, 70 insertions(+), 7 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index c0b94bc..649a0c2 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -17449,7 +17449,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); pg_create_physical_replication_slot - pg_create_physical_replication_slot(slot_name name , immediately_reserve boolean ) + pg_create_physical_replication_slot(slot_name name, immediately_reserve boolean, failover boolean) (slot_name name, xlog_position pg_lsn) @@ -17460,7 +17460,10 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); when true, specifies that the LSN for this replication slot be reserved immediately; otherwise the LSN is reserved on first connection from a streaming - replication client. Streaming changes from a physical slot is only + replication client. If failover is true + then the slot is created as a failover slot; see . + Streaming changes from a physical slot is only possible with the streaming-replication protocol — see . This function corresponds to the replication protocol command CREATE_REPLICATION_SLOT @@ -17489,7 +17492,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); pg_create_logical_replication_slot - pg_create_logical_replication_slot(slot_name name, plugin name) + pg_create_logical_replication_slot(slot_name name, plugin name, failover boolean) (slot_name name, xlog_position pg_lsn) @@ -17497,8 +17500,10 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); Creates a new logical (decoding) replication slot named slot_name using the output plugin - plugin. A call to this function has the same - effect as the replication protocol command + plugin. If failover + is true the slot is created as a failover + slot; see . A call to + this function has the same effect as the replication protocol command CREATE_REPLICATION_SLOT ... LOGICAL. diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index 6cb690c..4b75175 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -949,6 +949,47 @@ primary_slot_name = 'node_a_slot' + + + Failover slots + + + Normally a replication slot is not preserved across backup and restore + (such as by pg_basebackup) and is not + replicated to standbys. Slots are automatically + dropped when starting up as a streaming replica or in archive + recovery (PITR) mode. + + + + To make it possible to for an application to consistently follow + failover when a replica is promoted to a new master a slot may be + created as a failover slot. A failover slot may + only be created, replayed from or dropped on a master server. Changes to + the slot are written to WAL and replicated to standbys. When a standby + is promoted applications may connect to the slot on the standby and + resume replay from it at a consistent point, as if it was the original + master. Failover slots may not be used to replay from a standby before + promotion. + + + + Non-failover slots may be created on and used from a replica. This is + currently limited to physical slots as logical decoding is not supported + on replica server. + + + + When a failover slot created on the master has the same name as a + non-failover slot on a replica server the non-failover slot will be + automatically dropped. Any client currently connected will be + disconnected with an error indicating a conflict with recovery. It + is strongly recommended that you avoid creating failover slots with + the same name as slots on replicas. + + + + diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml index e841348..c7b43ed 100644 --- a/doc/src/sgml/logicaldecoding.sgml +++ b/doc/src/sgml/logicaldecoding.sgml @@ -280,7 +280,7 @@ $ pg_recvlogical -d postgres --slot test --drop-slot The commands - CREATE_REPLICATION_SLOT slot_name LOGICAL output_plugin + CREATE_REPLICATION_SLOT slot_name LOGICAL output_plugin FAILOVER diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 522128e..33b6830 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1434,7 +1434,7 @@ The commands accepted in walsender mode are: - CREATE_REPLICATION_SLOT slot_name { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin } + CREATE_REPLICATION_SLOT slot_name { PHYSICAL RESERVE_WAL | LOGICAL output_plugin } FAILOVER CREATE_REPLICATION_SLOT @@ -1474,6 +1474,17 @@ The commands accepted in walsender mode are: + + + FAILOVER + + + Create this slot as a + failover slot. + + + + @@ -1829,6 +1840,12 @@ The commands accepted in walsender mode are: to process the output for streaming. + + Logical replication automatically follows timeline switches. It is + not necessary or possible to supply a TIMELINE + option like in physical replication. + + SLOT slot_name -- 2.1.0