public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Paul A Jungwirth <pj@illuminatedcomputing.com>
To: pgsql-docs@lists.postgresql.org
Subject: Streaming Replication vs Logical
Date: Fri, 11 Oct 2024 15:53:41 -0700
Message-ID: <CA+renyULt3VBS1cRFKUfT2=5dr61xBOZdAZ-CqX3XLGXqY-aTQ@mail.gmail.com> (raw)
Our docs seem to contrast "streaming replication" to logical, but
these are not really opposites. Sometimes when they say "streaming"
they mean "physical".
Probably this is historical: at first physical replication was the
only kind of streaming we had.
Personally this has caused me a lot of confusion. For example,
recently when I read "Synchronous replication (see Section 26.2.8) is
only supported on replication slots used over the streaming
replication interface," I took it to mean synchronous replication only
worked for physical replication, not logical. But actually here the
contrast is between the streaming protocol and SQL commands. I think
it would help if the docs elsewhere took more care to say "physical"
not "streaming" when that is the meaning.
This patch fixes a callout note in the Logical Decoding section. It
was sort of vague before. It dates back to the original commit
documenting logical decoding, so I'm not sure of the original motive.
I think the new text is more precise and about the other use for
replication slots, and also clearly separates streaming replication
from physical-vs-logical replication. (I used the word "typically"
because you *can* have a standby with logical replication, although
elsewhere we warn it may not be as robust.)
I also tried to fix the first three paragraphs of
https://www.postgresql.org/docs/current/runtime-config-replication.html
which seem to be setting up a distinction between streaming
replication and logical. This is tricky, because (1) we are trying to
introduce how we've organized different config parameters, and some
affect both physical and logical replication (e.g.
max_replication_slots and wal_retrieve_retry_interval) (2) you can use
logical replication without streaming (e.g.
pg_logical_slot_get_changes).
While I was making edits there, I took out some language about
"built-in" and "feature", which seem like unnecessary wordiness.
I also added "physical" to a couple places in
https://www.postgresql.org/docs/current/warm-standby.html as well as a
Note callout to clarify that the whole page is really about using
physical replication. Technically you could use logical replication to
run a standby, but that seems like a separate discussion.
Yours,
--
Paul ~{:-)
pj@illuminatedcomputing.com
Attachments:
[application/octet-stream] v1-0001-Distinguish-between-streaming-replication-and-phy.patch (5.2K, 2-v1-0001-Distinguish-between-streaming-replication-and-phy.patch)
download | inline diff:
From 7669ce908f70a7f6c1678cdc92be5c0685131e11 Mon Sep 17 00:00:00 2001
From: "Paul A. Jungwirth" <pj@illuminatedcomputing.com>
Date: Fri, 11 Oct 2024 15:43:10 -0700
Subject: [PATCH v1] Distinguish between streaming replication and physical
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 | 13 +++++++------
doc/src/sgml/high-availability.sgml | 12 ++++++++++--
doc/src/sgml/logicaldecoding.sgml | 6 +++---
3 files changed, 20 insertions(+), 11 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 9707d5238da..8a59842d72d 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4367,15 +4367,16 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
<title>Replication</title>
<para>
- These settings control the behavior of the built-in
- <firstterm>streaming replication</firstterm> feature (see
- <xref linkend="streaming-replication"/>), and the built-in
- <firstterm>logical replication</firstterm> feature (see
+ These settings control the behavior of
+ <firstterm>streaming replication</firstterm>,
+ both <firstterm>physical replication</firstterm>
+ (see <xref linkend="streaming-replication"/>) and
+ <firstterm>logical replication</firstterm> (see
<xref linkend="logical-replication"/>).
</para>
<para>
- For <emphasis>streaming replication</emphasis>, servers will be either a
+ For <emphasis>physical replication</emphasis>, 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 <xref linkend="cascading-replication"/>) is used, standby servers
@@ -4768,7 +4769,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
These settings control the behavior of a
<link linkend="standby-server-operation">standby server</link>
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.
</para>
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index acf3ac0601d..331f90e4521 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -151,7 +151,7 @@ protocol to make nodes agree on a serializable transactional order.
</para>
<para>
A standby server can be implemented using file-based log shipping
- (<xref linkend="warm-standby"/>) or streaming replication (see
+ (<xref linkend="warm-standby"/>) or streaming physical replication (see
<xref linkend="streaming-replication"/>), or a combination of both. For
information on hot standby, see <xref linkend="hot-standby"/>.
</para>
@@ -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 <xref linkend="guc-restore-command"/>) 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
<filename>pg_wal</filename> 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.
</para>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
+
<para>
Streaming replication is asynchronous by default
(see <xref linkend="synchronous-replication"/>), in which case there is
diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 1c4ae38f1b9..706f0ea6fba 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
</para>
<note>
- <para><productname>PostgreSQL</productname> also has streaming replication slots
- (see <xref linkend="streaming-replication"/>), but they are used somewhat
- differently there.
+ <para><productname>PostgreSQL</productname> can also use streaming replication slots
+ to maintain a standby server (see <xref linkend="streaming-replication"/>), but
+ typically those use physical replication, not logical.
</para>
</note>
--
2.45.0
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: pj@illuminatedcomputing.com, pgsql-docs@lists.postgresql.org
Subject: Re: Streaming Replication vs Logical
In-Reply-To: <CA+renyULt3VBS1cRFKUfT2=5dr61xBOZdAZ-CqX3XLGXqY-aTQ@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox