1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>55.5. Logical Streaming Replication Protocol</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="protocol-replication.html" title="55.4. Streaming Replication Protocol" /><link rel="next" href="protocol-message-types.html" title="55.6. Message Data Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.5. Logical Streaming Replication Protocol</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-message-types.html" title="55.6. Message Data Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-LOGICAL-REPLICATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.5. Logical Streaming Replication Protocol <a href="#PROTOCOL-LOGICAL-REPLICATION" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="protocol-logical-replication.html#PROTOCOL-LOGICAL-REPLICATION-PARAMS">55.5.1. Logical Streaming Replication Parameters</a></span></dt><dt><span class="sect2"><a href="protocol-logical-replication.html#PROTOCOL-LOGICAL-MESSAGES">55.5.2. Logical Replication Protocol Messages</a></span></dt><dt><span class="sect2"><a href="protocol-logical-replication.html#PROTOCOL-LOGICAL-MESSAGES-FLOW">55.5.3. Logical Replication Protocol Message Flow</a></span></dt></dl></div><p>
This section describes the logical replication protocol, which is the message
flow started by the <code class="literal">START_REPLICATION</code>
<code class="literal">SLOT</code> <em class="replaceable"><code>slot_name</code></em>
<code class="literal">LOGICAL</code> replication command.
</p><p>
The logical streaming replication protocol builds on the primitives of
the physical streaming replication protocol.
</p><p>
<span class="productname">PostgreSQL</span> logical decoding supports output
plugins. <code class="literal">pgoutput</code> is the standard one used for
the built-in logical replication.
</p><div class="sect2" id="PROTOCOL-LOGICAL-REPLICATION-PARAMS"><div class="titlepage"><div><div><h3 class="title">55.5.1. Logical Streaming Replication Parameters <a href="#PROTOCOL-LOGICAL-REPLICATION-PARAMS" class="id_link">#</a></h3></div></div></div><p>
Using the <code class="literal">START_REPLICATION</code> command,
<code class="literal">pgoutput</code> accepts the following options:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
proto_version
</span></dt><dd><p>
Protocol version. Currently versions <code class="literal">1</code>, <code class="literal">2</code>,
<code class="literal">3</code>, and <code class="literal">4</code> are supported. A valid
version is required.
</p><p>
Version <code class="literal">2</code> is supported only for server version 14
and above, and it allows streaming of large in-progress transactions.
</p><p>
Version <code class="literal">3</code> is supported only for server version 15
and above, and it allows streaming of two-phase commits.
</p><p>
Version <code class="literal">4</code> is supported only for server version 16
and above, and it allows streams of large in-progress transactions to
be applied in parallel.
</p></dd><dt><span class="term">
publication_names
</span></dt><dd><p>
Comma separated list of publication names for which to subscribe
(receive changes). The individual publication names are treated
as standard objects names and can be quoted the same as needed.
At least one publication name is required.
</p></dd><dt><span class="term">
binary
</span></dt><dd><p>
Boolean option to use binary transfer mode. Binary mode is faster
than the text mode but slightly less robust.
</p></dd><dt><span class="term">
messages
</span></dt><dd><p>
Boolean option to enable sending the messages that are written
by <code class="function">pg_logical_emit_message</code>.
</p></dd><dt><span class="term">
streaming
</span></dt><dd><p>
Boolean option to enable streaming of in-progress transactions.
It accepts an additional value "parallel" to enable sending extra
information with some messages to be used for parallelisation.
Minimum protocol version 2 is required to turn it on. Minimum protocol
version 4 is required for the "parallel" option.
</p></dd><dt><span class="term">
two_phase
</span></dt><dd><p>
Boolean option to enable two-phase transactions. Minimum protocol
version 3 is required to turn it on.
</p></dd><dt><span class="term">
origin
</span></dt><dd><p>
Option to send changes by their origin. Possible values are "none"
to only send the changes that have no origin associated, or "any"
to send the changes regardless of their origin. This can be used
to avoid loops (infinite replication of the same data) among
replication nodes.
</p></dd></dl></div><p>
</p></div><div class="sect2" id="PROTOCOL-LOGICAL-MESSAGES"><div class="titlepage"><div><div><h3 class="title">55.5.2. Logical Replication Protocol Messages <a href="#PROTOCOL-LOGICAL-MESSAGES" class="id_link">#</a></h3></div></div></div><p>
The individual protocol messages are discussed in the following
subsections. Individual messages are described in
<a class="xref" href="protocol-logicalrep-message-formats.html" title="55.9. Logical Replication Message Formats">Section 55.9</a>.
</p><p>
All top-level protocol messages begin with a message type byte.
While represented in code as a character, this is a signed byte with no
associated encoding.
</p><p>
Since the streaming replication protocol supplies a message length there
is no need for top-level protocol messages to embed a length in their
header.
</p></div><div class="sect2" id="PROTOCOL-LOGICAL-MESSAGES-FLOW"><div class="titlepage"><div><div><h3 class="title">55.5.3. Logical Replication Protocol Message Flow <a href="#PROTOCOL-LOGICAL-MESSAGES-FLOW" class="id_link">#</a></h3></div></div></div><p>
With the exception of the <code class="literal">START_REPLICATION</code> command and
the replay progress messages, all information flows only from the backend
to the frontend.
</p><p>
The logical replication protocol sends individual transactions one by one.
This means that all messages between a pair of Begin and Commit messages
belong to the same transaction. Similarly, all messages between a pair of
Begin Prepare and Prepare messages belong to the same transaction.
It also sends changes of large in-progress transactions between a pair of
Stream Start and Stream Stop messages. The last stream of such a transaction
contains a Stream Commit or Stream Abort message.
</p><p>
Every sent transaction contains zero or more DML messages (Insert,
Update, Delete). In case of a cascaded setup it can also contain Origin
messages. The origin message indicates that the transaction originated on
different replication node. Since a replication node in the scope of logical
replication protocol can be pretty much anything, the only identifier
is the origin name. It's downstream's responsibility to handle this as
needed (if needed). The Origin message is always sent before any DML
messages in the transaction.
</p><p>
Every DML message contains a relation OID, identifying the publisher's
relation that was acted on. Before the first DML message for a given
relation OID, a Relation message will be sent, describing the schema of
that relation. Subsequently, a new Relation message will be sent if
the relation's definition has changed since the last Relation message
was sent for it. (The protocol assumes that the client is capable of
remembering this metadata for as many relations as needed.)
</p><p>
Relation messages identify column types by their OIDs. In the case
of a built-in type, it is assumed that the client can look up that
type OID locally, so no additional data is needed. For a non-built-in
type OID, a Type message will be sent before the Relation message,
to provide the type name associated with that OID. Thus, a client that
needs to specifically identify the types of relation columns should
cache the contents of Type messages, and first consult that cache to
see if the type OID is defined there. If not, look up the type OID
locally.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol-replication.html" title="55.4. Streaming Replication Protocol">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-message-types.html" title="55.6. Message Data Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.4. Streaming Replication Protocol </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.6. Message Data Types</td></tr></table></div></body></html>
|
