From 8e80fd6a889544756863a9641b23eae8484ebb4e Mon Sep 17 00:00:00 2001 From: Robert Treat Date: Fri, 24 Jan 2025 00:12:45 -0500 Subject: [PATCH v2] Distinguish between streaming replication and physical Content-Type: text/plain; charset="utf-8" Our docs still use the term "streaming replication" in places where they really mean physical replication. These changes try to clarify the language around streaming replication, physical replication, and logical replication. In particular we should avoid suggesting that "streaming" and "logical" are opposites or alternatives. --- doc/src/sgml/config.sgml | 29 ++++++++++++++------------- doc/src/sgml/high-availability.sgml | 12 +++++++++-- doc/src/sgml/logical-replication.sgml | 6 +++--- doc/src/sgml/logicaldecoding.sgml | 6 +++--- 4 files changed, 31 insertions(+), 22 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index a782f10998..c4cceb8466 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -2026,7 +2026,7 @@ include_dir 'conf.d' Specifies the maximum amount of memory to be used by logical decoding, before some of the decoded changes are written to local disk. This - limits the amount of memory used by logical streaming replication + limits the amount of memory used by streaming logical replication connections. It defaults to 64 megabytes (64MB). Since each replication connection only uses a single buffer of this size, and an installation normally doesn't have many such connections @@ -3592,7 +3592,7 @@ include_dir 'conf.d' difference between the two modes, but when set to always the WAL archiver is enabled also during archive recovery or standby mode. In always mode, all files restored from the archive - or streamed with streaming replication will be archived (again). See + or streamed with streaming physical replication will be archived (again). See for details. @@ -3698,7 +3698,7 @@ include_dir 'conf.d' full files. Therefore, it is unwise to use a very short archive_timeout — it will bloat your archive storage. archive_timeout settings of a minute or so are - usually reasonable. You should consider using streaming replication, + usually reasonable. You should consider using streaming physical replication, instead of archiving, if you want data to be copied off the primary server more quickly than that. If this value is specified without units, it is taken as seconds. @@ -3723,7 +3723,7 @@ include_dir 'conf.d' This section describes the settings that apply to recovery in general, - affecting crash recovery, streaming replication and archive-based + affecting crash recovery, streaming physical replication and archive-based replication. @@ -3833,7 +3833,7 @@ include_dir 'conf.d' The local shell command to execute to retrieve an archived segment of the WAL file series. This parameter is required for archive recovery, - but optional for streaming replication. + but optional for streaming physical replication. Any %f in the string is replaced by the name of the file to retrieve from the archive, and any %p is replaced by the copy destination path name @@ -4259,15 +4259,16 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows Replication - These settings control the behavior of the built-in - streaming replication feature (see - ), and the built-in - logical replication feature (see + These settings control the behavior of + streaming replication, + both physical replication + (see ) and + logical replication (see ). - For streaming replication, servers will be either a + For physical replication, servers will be either a primary or a standby server. Primaries can send data, while standbys are always receivers of replicated data. When cascading replication (see ) is used, standby servers @@ -4664,7 +4665,7 @@ ANY num_sync ( standby server that is - to receive replication data. Their values on the primary server + to receive physical replication data. Their values on the primary server are irrelevant. @@ -4802,7 +4803,7 @@ ANY num_sync ( . max_standby_streaming_delay applies when WAL data is - being received via streaming replication. + being received via streaming physical replication. If this value is specified without units, it is taken as milliseconds. The default is 30 seconds. A value of -1 allows the standby to wait forever for conflicting @@ -4931,7 +4932,7 @@ ANY num_sync ( num_sync ( ) or streaming replication (see + () or streaming physical replication (see ), or a combination of both. For information on hot standby, see . @@ -628,7 +628,7 @@ protocol to make nodes agree on a serializable transactional order. In standby mode, the server continuously applies WAL received from the primary server. The standby server can read WAL from a WAL archive (see ) or directly from the primary - over a TCP connection (streaming replication). The standby server will + over a TCP connection (streaming physical replication). The standby server will also attempt to restore any WAL found in the standby cluster's pg_wal directory. That typically happens after a server restart, when the standby replays again WAL that was streamed from the @@ -772,6 +772,14 @@ archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r' generated, without waiting for the WAL file to be filled. + + + This discussion of streaming replication assumes physical replication. + Although you could treat a logical replication subscriber as a warm standby, + it would require some differences to what is described here. + + + Streaming replication is asynchronous by default (see ), in which case there is diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index ab683cf111..b0361fc061 100644 --- a/doc/src/sgml/logical-replication.sgml +++ b/doc/src/sgml/logical-replication.sgml @@ -6,7 +6,7 @@ Logical replication is a method of replicating data objects and their changes, based upon their replication identity (usually a primary key). We - use the term logical in contrast to physical replication, which uses exact + use the term logical replication in contrast to physical replication, which uses exact block addresses and byte-by-byte replication. PostgreSQL supports both mechanisms concurrently, see . Logical replication allows fine-grained control over both data replication and @@ -2057,8 +2057,8 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER Monitoring - Because logical replication is based on a similar architecture as - physical streaming replication, + Because streaming logical replication is based on a similar architecture as + streaming physical replication, the monitoring on a publication node is similar to monitoring of a physical replication primary (see ). diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml index 1c4ae38f1b..706f0ea6fb 100644 --- a/doc/src/sgml/logicaldecoding.sgml +++ b/doc/src/sgml/logicaldecoding.sgml @@ -275,9 +275,9 @@ postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NU - PostgreSQL also has streaming replication slots - (see ), but they are used somewhat - differently there. + PostgreSQL can also use streaming replication slots + to maintain a standby server (see ), but + typically those use physical replication, not logical. -- 2.24.3 (Apple Git-128)