begriffs open source - ai-pg/blob - full-docs/src/sgml/html/protocol-logical-replication.html

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