From: Andres Freund Date: Wed, 29 Jan 2014 15:28:57 +0000 (+0100) Subject: Initial cut at replication slot docs. X-Git-Url: http://git.postgresql.org/gitweb/?a=commitdiff_plain;h=ba8a748a35eb84b3d16deb63af95ed7735e11e07;p=users%2Frhaas%2Fpostgres.git Initial cut at replication slot docs. --- diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 2230c9392c..5a7ac0ce98 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -233,6 +233,11 @@ query rewrite rules + + pg_replication_slots + replication slot information + + pg_seclabel security labels on database objects @@ -5157,6 +5162,101 @@ + + <structname>pg_replication_slots</structname> + + + pg_replication_slots + + + + The pg_replication_slots view provides a listing + of all replication slots that currently exist on the database cluster, + along with their current state. + + + + For more on replication slots, + see . + + + + + <structname>pg_replication_slots</structname> Columns + + + + + Name + Type + References + Description + + + + + + slot_name + text + + A unique, cluster-wide identifier for the replication slot + + + + slot_type + text + + The slot type - physical or logical + + + + datoid + oid + pg_database.oid + The oid of the database this slot is associated with, or + null. Only logical slots have an associated database. + + + + database + text + pg_database.datname + The name of the database this slot is associated with, or + null. Only logical slots have an associated database. + + + + active + boolean + + True if this slot is currently actively being used + + + + data_xmin + xid + + The xmin, or oldest transaction ID, of + user data that this slot forces to be retained in the database. + VACUUM cannot remove tuples whose + xmax is greater than this. + + + + + restart_lsn + text + + The address (LSN) of oldest WAL which still + might be required by the consumer of this slot and thus won't be + automaticall removed during checkpoints. + + + + +
+ + <structname>pg_seclabel</structname> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 14ed6c7a53..dabe948f71 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -2311,6 +2311,25 @@ include 'filename' + + max_replication_slots (integer) + + max_replication_slots configuration parameter + + + + Specifies the maximum number of replication slots + (see that can exist at the + same time. The default is zero. This parameter can only be set at + server start. + wal_level must be set + to archive 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. + + + + wal_keep_segments (integer) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index c0a75de0e7..38f1b50612 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -16095,6 +16095,76 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); + + Replication Functions + + + PostgreSQL exposes a number of functions for controlling and interacting + with replication features. See + and . + + + + Many of these functions have equivalent commands in the replication + protocol; see . + + + + The sections , and are also relevant for replication. + + + + Replication <acronym>SQL</acronym> Functions + + + + Function + Return Type + Description + + + + + + + create_physical_replication_slot + + create_physical_replication_slot(slotname text, plugin text) + + + (slotname text, xlog_position text) + + + Creates a new physical replication slot named + slotname. Streaming changes from a physical slot + is only possible with the walsender protocol - see . Corresponds to the walsender protocol + command CREATE_REPLICATION_SLOT ... PHYSICAL. + + + + + + drop_replication_slot + + drop_replication_slot(slotname text) + + + (slotname text) + + + Drops the physical or logical replication slot + named slotname. Same as walsender protocol + command DROP_REPLICATION_SLOT. + + + + +
+ + Database Object Management Functions diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index e2e5ac93ab..701e83acaa 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 pg_hba.conf with the database field set to replication. Also ensure 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 max_replication_slots is set sufficiently high + as well. @@ -749,14 +751,15 @@ archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r' - If you use streaming replication without file-based continuous - archiving, you have to set 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, wal_keep_segments is not required as the standby can always - use the archive to catch up. + If streaming replication is used without file-based continuous archiving, + either wal_keep_segments has to be set to a value high enough, + or replication slots have to be used, 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, wal_keep_segments is not required as the standby + can always use the archive to catch up provided it retains enough + segments. @@ -871,6 +874,90 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' + + Replication Slots + + Replication Slots + + + A consumer of streaming replication requires the sender to retain + resources it requires: WAL segments that haven't been received by a + downstream node may not be removed lest the standby will either unable to + catch up, or needs to rely on externally maintained data via + restore_command + (see ). In many scenarios the + standby also relies on the primary not to remove rows it still needs + (see ). + + + wal_keep_segments provides protection against required + WAL being removed, but it's a simple, imprecise method to retain enough + data, as it will often set to high values to retain enough WAL in case of + outages. + + + hot_standby_feedback + and vacuum_defer_cleanup_age provide protection against + relevant rows being removed by vacuum, but the former looses it's + protection during a connection loss of the replication connection and the + latter needs to be set to high values to provide safety. + + + The alternative is to use replication slots which provide a way to + register a standby's state on the primary (or one node up in + a cascading replication + setup) preventing it from removing resources that are required. When a + replication slot is used the upstream node will not remove required WAL + and if hot_standby_feedback is enable, the slot will + also be used to enforce that the relevant rows won't be removed. + + + Querying and manipulating replication slots + + A replication slot is identified by a single, cluster wide, name + consisting only out of lower case alphanumeric characters and the + underscore character. + + + Existing replication slots and their state can be seen in the + pg_replication_slots + view. + + + They can be created and dropped either via the streaming replication + protocol (see ) or by SQL accessible + functions (see ). + + + + Configuration Example + + To use streaming replication with a replication slot one first has to be + created: + +postgres=# SELECT * FROM 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 | data_xmin | restart_lsn +-------------+-----------+--------+----------+--------+-----------+------------- + node_a_slot | physical | 0 | | f | 0 | 0/0 +(1 row) + + After that the standby's recovery.conf needs to be changed to + specify primary_slotname. A simple example of such + a recovery.conf is: + +standby_mode = 'on' +primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' +primary_slotname = 'node_a_slot' + + + + + Cascading Replication diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 7d99976a49..30bba3286d 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1401,15 +1401,39 @@ The commands accepted in walsender mode are: - START_REPLICATION XXX/XXX TIMELINE tli + CREATE_REPLICATION_SLOT SLOT slotname PHYSICAL + CREATE_REPLICATION_SLOT - Instructs server to start streaming WAL, starting at - WAL position XXX/XXX on timeline - 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. + Create a physical replication + slot. See for more about + replication slots. + + + + SLOT slotname + + + The name of the slot to create. Must be a valid replication slot + name (see ). + + + + + + + + + START_REPLICATION [SLOT slotname] [PHYSICAL] XXX/XXX TIMELINE tli + + + Instructs server to start streaming physical WAL records, starting at + WAL position XXX/XXX. If specified, + streaming starts on timeline 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. @@ -1443,6 +1467,13 @@ The commands accepted in walsender mode are: client contains a message of one of the following formats: + + If a slot's name is provided + via slotname, it will be updated with + replication progress while START_REPLICATION is in progress ensuring + that no important resources are released. + + @@ -1719,6 +1750,26 @@ The commands accepted in walsender mode are: + + DROP_REPLICATION_SLOT SLOT slotname + + + Drops a replication slot, freeing any reserved server-side resources. If + the slot is currently in use by an active connection this command fails. + + + + SLOT slotname + + + The name of the slot to drop. + + + + + + + BASE_BACKUP [LABEL 'label'] [PROGRESS] [FAST] [WAL] [NOWAIT] diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml index 4a97bb7a9c..b69ce287c8 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 + + primary_slotname (string) + + primary_slotname recovery parameter + + + + 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 ). + This setting has no effect if primary_conninfo is not + set. + + + trigger_file (string)