begriffs open source - ai-pg/blob - full-docs/txt/protocol-logical-replication.txt

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