begriffs open source - ai-pg/blob - full-docs/src/sgml/html/logicaldecoding-explanation.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>47.2. Logical Decoding Concepts</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="logicaldecoding-example.html" title="47.1. Logical Decoding Examples" /><link rel="next" href="logicaldecoding-walsender.html" title="47.3. Streaming Replication Protocol Interface" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">47.2. Logical Decoding Concepts</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-example.html" title="47.1. Logical Decoding Examples">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 47. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 47. Logical Decoding</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="logicaldecoding-walsender.html" title="47.3. Streaming Replication Protocol Interface">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-EXPLANATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">47.2. Logical Decoding Concepts <a href="#LOGICALDECODING-EXPLANATION" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logicaldecoding-explanation.html#LOGICALDECODING-EXPLANATION-LOG-DEC">47.2.1. Logical Decoding</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS">47.2.2. Replication Slots</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS-SYNCHRONIZATION">47.2.3. Replication Slot Synchronization</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#LOGICALDECODING-EXPLANATION-OUTPUT-PLUGINS">47.2.4. Output Plugins</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-explanation.html#LOGICALDECODING-EXPLANATION-EXPORTED-SNAPSHOTS">47.2.5. Exported Snapshots</a></span></dt></dl></div><div class="sect2" id="LOGICALDECODING-EXPLANATION-LOG-DEC"><div class="titlepage"><div><div><h3 class="title">47.2.1. Logical Decoding <a href="#LOGICALDECODING-EXPLANATION-LOG-DEC" class="id_link">#</a></h3></div></div></div><a id="id-1.8.14.8.2.2" class="indexterm"></a><p>
   3      Logical decoding is the process of extracting all persistent changes
   4      to a database's tables into a coherent, easy to understand format which
   5      can be interpreted without detailed knowledge of the database's internal
   6      state.
   7     </p><p>
   8      In <span class="productname">PostgreSQL</span>, logical decoding is implemented
   9      by decoding the contents of the <a class="link" href="wal.html" title="Chapter 28. Reliability and the Write-Ahead Log">write-ahead
  10      log</a>, which describe changes on a storage level, into an
  11      application-specific form such as a stream of tuples or SQL statements.
  12     </p></div><div class="sect2" id="LOGICALDECODING-REPLICATION-SLOTS"><div class="titlepage"><div><div><h3 class="title">47.2.2. Replication Slots <a href="#LOGICALDECODING-REPLICATION-SLOTS" class="id_link">#</a></h3></div></div></div><a id="id-1.8.14.8.3.2" class="indexterm"></a><p>
  13      In the context of logical replication, a slot represents a stream of
  14      changes that can be replayed to a client in the order they were made on
  15      the origin server. Each slot streams a sequence of changes from a single
  16      database.
  17     </p><div class="note"><h3 class="title">Note</h3><p><span class="productname">PostgreSQL</span> also has streaming replication slots
  18      (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="26.2.5. Streaming Replication">Section 26.2.5</a>), but they are used somewhat
  19      differently there.
  20      </p></div><p>
  21      A replication slot has an identifier that is unique across all databases
  22      in a <span class="productname">PostgreSQL</span> cluster. Slots persist
  23      independently of the connection using them and are crash-safe.
  24     </p><p>
  25      A logical slot will emit each change just once in normal operation.
  26      The current position of each slot is persisted only at checkpoint, so in
  27      the case of a crash the slot might return to an earlier LSN, which will
  28      then cause recent changes to be sent again when the server restarts.
  29      Logical decoding clients are responsible for avoiding ill effects from
  30      handling the same message more than once.  Clients may wish to record
  31      the last LSN they saw when decoding and skip over any repeated data or
  32      (when using the replication protocol) request that decoding start from
  33      that LSN rather than letting the server determine the start point.
  34      The Replication Progress Tracking feature is designed for this purpose,
  35      refer to <a class="link" href="replication-origins.html" title="Chapter 48. Replication Progress Tracking">replication origins</a>.
  36     </p><p>
  37      Multiple independent slots may exist for a single database. Each slot has
  38      its own state, allowing different consumers to receive changes from
  39      different points in the database change stream. For most applications, a
  40      separate slot will be required for each consumer.
  41     </p><p>
  42      A logical replication slot knows nothing about the state of the
  43      receiver(s).  It's even possible to have multiple different receivers using
  44      the same slot at different times; they'll just get the changes following
  45      on from when the last receiver stopped consuming them. Only one receiver
  46      may consume changes from a slot at any given time.
  47     </p><p>
  48      A logical replication slot can also be created on a hot standby. To prevent
  49      <code class="command">VACUUM</code> from removing required rows from the system
  50      catalogs, <code class="varname">hot_standby_feedback</code> should be set on the
  51      standby. In spite of that, if any required rows get removed, the slot gets
  52      invalidated. It's highly recommended to use a physical slot between the
  53      primary and the standby. Otherwise, <code class="varname">hot_standby_feedback</code>
  54      will work but only while the connection is alive (for example a node
  55      restart would break it). Then, the primary may delete system catalog rows
  56      that could be needed by the logical decoding on the standby (as it does
  57      not know about the <code class="literal">catalog_xmin</code> on the standby).
  58      Existing logical slots on standby also get invalidated if
  59      <code class="varname">wal_level</code> on the primary is reduced to less than
  60      <code class="literal">logical</code>.
  61      This is done as soon as the standby detects such a change in the WAL stream.
  62      It means that, for walsenders that are lagging (if any), some WAL records up
  63      to the <code class="varname">wal_level</code> parameter change on the primary won't be
  64      decoded.
  65     </p><p>
  66      Creation of a logical slot requires information about all the currently
  67      running transactions. On the primary, this information is available
  68      directly, but on a standby, this information has to be obtained from
  69      primary. Thus, slot creation may need to wait for some activity to happen
  70      on the primary. If the primary is idle, creating a logical slot on
  71      standby may take noticeable time. This can be sped up by calling the
  72      <code class="function">pg_log_standby_snapshot</code> function on the primary.
  73     </p><div class="caution"><h3 class="title">Caution</h3><p>
  74       Replication slots persist across crashes and know nothing about the state
  75       of their consumer(s). They will prevent removal of required resources
  76       even when there is no connection using them. This consumes storage
  77       because neither required WAL nor required rows from the system catalogs
  78       can be removed by <code class="command">VACUUM</code> as long as they are required by a replication
  79       slot.  In extreme cases this could cause the database to shut down to prevent
  80       transaction ID wraparound (see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="24.1.5. Preventing Transaction ID Wraparound Failures">Section 24.1.5</a>).
  81       So if a slot is no longer required it should be dropped.
  82      </p></div></div><div class="sect2" id="LOGICALDECODING-REPLICATION-SLOTS-SYNCHRONIZATION"><div class="titlepage"><div><div><h3 class="title">47.2.3. Replication Slot Synchronization <a href="#LOGICALDECODING-REPLICATION-SLOTS-SYNCHRONIZATION" class="id_link">#</a></h3></div></div></div><p>
  83      The logical replication slots on the primary can be synchronized to
  84      the hot standby by using the <code class="literal">failover</code> parameter of
  85      <a class="link" href="functions-admin.html#PG-CREATE-LOGICAL-REPLICATION-SLOT">
  86      <code class="function">pg_create_logical_replication_slot</code></a>, or by
  87      using the <a class="link" href="sql-createsubscription.html#SQL-CREATESUBSCRIPTION-PARAMS-WITH-FAILOVER">
  88      <code class="literal">failover</code></a> option of
  89      <code class="command">CREATE SUBSCRIPTION</code> during slot creation.
  90      Additionally, enabling <a class="link" href="runtime-config-replication.html#GUC-SYNC-REPLICATION-SLOTS">
  91      <code class="varname">sync_replication_slots</code></a> on the standby
  92      is required. By enabling <a class="link" href="runtime-config-replication.html#GUC-SYNC-REPLICATION-SLOTS">
  93      <code class="varname">sync_replication_slots</code></a>
  94      on the standby, the failover slots can be synchronized periodically in
  95      the slotsync worker. For the synchronization to work, it is mandatory to
  96      have a physical replication slot between the primary and the standby (i.e.,
  97      <a class="link" href="runtime-config-replication.html#GUC-PRIMARY-SLOT-NAME"><code class="varname">primary_slot_name</code></a>
  98      should be configured on the standby), and
  99      <a class="link" href="runtime-config-replication.html#GUC-HOT-STANDBY-FEEDBACK"><code class="varname">hot_standby_feedback</code></a>
 100      must be enabled on the standby. It is also necessary to specify a valid
 101      <code class="literal">dbname</code> in the
 102      <a class="link" href="runtime-config-replication.html#GUC-PRIMARY-CONNINFO"><code class="varname">primary_conninfo</code></a>.
 103      It's highly recommended that the said physical replication slot is named in
 104      <a class="link" href="runtime-config-replication.html#GUC-SYNCHRONIZED-STANDBY-SLOTS"><code class="varname">synchronized_standby_slots</code></a>
 105      list on the primary, to prevent the subscriber from consuming changes
 106      faster than the hot standby. Even when correctly configured, some latency
 107      is expected when sending changes to logical subscribers due to the waiting
 108      on slots named in
 109      <a class="link" href="runtime-config-replication.html#GUC-SYNCHRONIZED-STANDBY-SLOTS"><code class="varname">synchronized_standby_slots</code></a>.
 110      When <code class="varname">synchronized_standby_slots</code> is utilized, the
 111      primary server will not completely shut down until the corresponding
 112      standbys, associated with the physical replication slots specified
 113      in <code class="varname">synchronized_standby_slots</code>, have confirmed
 114      receiving the WAL up to the latest flushed position on the primary server.
 115     </p><div class="note"><h3 class="title">Note</h3><p>
 116       While enabling <a class="link" href="runtime-config-replication.html#GUC-SYNC-REPLICATION-SLOTS">
 117       <code class="varname">sync_replication_slots</code></a> allows for automatic
 118       periodic synchronization of failover slots, they can also be manually
 119       synchronized using the <a class="link" href="functions-admin.html#PG-SYNC-REPLICATION-SLOTS">
 120       <code class="function">pg_sync_replication_slots</code></a> function on the standby.
 121       However, this function is primarily intended for testing and debugging and
 122       should be used with caution. Unlike automatic synchronization, it does not
 123       include cyclic retries, making it more prone to synchronization failures,
 124       particularly during initial sync scenarios where the required WAL files
 125       or catalog rows for the slot might have already been removed or are at risk
 126       of being removed on the standby. In contrast, automatic synchronization
 127       via <code class="varname">sync_replication_slots</code> provides continuous slot
 128       updates, enabling seamless failover and supporting high availability.
 129       Therefore, it is the recommended method for synchronizing slots.
 130      </p></div><p>
 131      When slot synchronization is configured as recommended,
 132      and the initial synchronization is performed either automatically or
 133      manually via <code class="function">pg_sync_replication_slots</code>, the standby
 134      can persist the synchronized slot only if the following condition is met:
 135      The logical replication slot on the primary must retain WALs and system
 136      catalog rows that are still available on the standby. This ensures data
 137      integrity and allows logical replication to continue smoothly after
 138      promotion.
 139      If the required WALs or catalog rows have already been purged from the
 140      standby, the slot will not be persisted to avoid data loss. In such
 141      cases, the following log message may appear:
 142 </p><pre class="programlisting">
 143 LOG:  could not synchronize replication slot "failover_slot"
 144 DETAIL:  Synchronization could lead to data loss, because the remote slot needs WAL at LSN 0/3003F28 and catalog xmin 754, but the standby has LSN 0/3003F28 and catalog xmin 756.
 145 </pre><p>
 146      If the logical replication slot is actively used by a consumer, no
 147      manual intervention is needed; the slot will advance automatically,
 148      and synchronization will resume in the next cycle. However, if no
 149      consumer is configured, it is advisable to manually advance the slot
 150      on the primary using <a class="link" href="functions-admin.html#PG-LOGICAL-SLOT-GET-CHANGES">
 151      <code class="function">pg_logical_slot_get_changes</code></a> or
 152      <a class="link" href="functions-admin.html#PG-LOGICAL-SLOT-GET-BINARY-CHANGES">
 153      <code class="function">pg_logical_slot_get_binary_changes</code></a>,
 154      allowing synchronization to proceed.
 155     </p><p>
 156      The ability to resume logical replication after failover depends upon the
 157      <a class="link" href="view-pg-replication-slots.html" title="53.20. pg_replication_slots">pg_replication_slots</a>.<code class="structfield">synced</code>
 158      value for the synchronized slots on the standby at the time of failover.
 159      Only persistent slots that have attained synced state as true on the standby
 160      before failover can be used for logical replication after failover.
 161      Temporary synced slots cannot be used for logical decoding, therefore
 162      logical replication for those slots cannot be resumed. For example, if the
 163      synchronized slot could not become persistent on the standby due to a
 164      disabled subscription, then the subscription cannot be resumed after
 165      failover even when it is enabled.
 166     </p><p>
 167      To resume logical replication after failover from the synced logical
 168      slots, the subscription's 'conninfo' must be altered to point to the
 169      new primary server. This is done using
 170      <a class="link" href="sql-altersubscription.html#SQL-ALTERSUBSCRIPTION-PARAMS-CONNECTION"><code class="command">ALTER SUBSCRIPTION ... CONNECTION</code></a>.
 171      It is recommended that subscriptions are first disabled before promoting
 172      the standby and are re-enabled after altering the connection string.
 173     </p><div class="caution"><h3 class="title">Caution</h3><p>
 174       There is a chance that the old primary is up again during the promotion
 175       and if subscriptions are not disabled, the logical subscribers may
 176       continue to receive data from the old primary server even after promotion
 177       until the connection string is altered. This might result in data
 178       inconsistency issues, preventing the logical subscribers from being
 179       able to continue replication from the new primary server.
 180      </p></div></div><div class="sect2" id="LOGICALDECODING-EXPLANATION-OUTPUT-PLUGINS"><div class="titlepage"><div><div><h3 class="title">47.2.4. Output Plugins <a href="#LOGICALDECODING-EXPLANATION-OUTPUT-PLUGINS" class="id_link">#</a></h3></div></div></div><p>
 181      Output plugins transform the data from the write-ahead log's internal
 182      representation into the format the consumer of a replication slot desires.
 183     </p></div><div class="sect2" id="LOGICALDECODING-EXPLANATION-EXPORTED-SNAPSHOTS"><div class="titlepage"><div><div><h3 class="title">47.2.5. Exported Snapshots <a href="#LOGICALDECODING-EXPLANATION-EXPORTED-SNAPSHOTS" class="id_link">#</a></h3></div></div></div><p>
 184      When a new replication slot is created using the streaming replication
 185      interface (see <a class="xref" href="protocol-replication.html#PROTOCOL-REPLICATION-CREATE-REPLICATION-SLOT">CREATE_REPLICATION_SLOT</a>), a
 186      snapshot is exported
 187      (see <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION" title="9.28.5. Snapshot Synchronization Functions">Section 9.28.5</a>), which will show
 188      exactly the state of the database after which all changes will be
 189      included in the change stream. This can be used to create a new replica by
 190      using <a class="link" href="sql-set-transaction.html" title="SET TRANSACTION"><code class="literal">SET TRANSACTION
 191      SNAPSHOT</code></a> to read the state of the database at the moment
 192      the slot was created. This transaction can then be used to dump the
 193      database's state at that point in time, which afterwards can be updated
 194      using the slot's contents without losing any changes.
 195     </p><p>
 196      Applications that do not require
 197      snapshot export may suppress it with the <code class="literal">SNAPSHOT 'nothing'</code>
 198      option.
 199     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-example.html" title="47.1. Logical Decoding Examples">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 47. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-walsender.html" title="47.3. Streaming Replication Protocol Interface">Next</a></td></tr><tr><td width="40%" align="left" valign="top">47.1. Logical Decoding Examples </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"> 47.3. Streaming Replication Protocol Interface</td></tr></table></div></body></html>