begriffs open source - ai-pg/blob - full-docs/src/sgml/html/logicaldecoding-streaming.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.9. Streaming of Large Transactions for Logical Decoding</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-synchronous.html" title="47.8. Synchronous Replication Support for Logical Decoding" /><link rel="next" href="logicaldecoding-two-phase-commits.html" title="47.10. Two-phase Commit Support for Logical Decoding" /></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.9. Streaming of Large Transactions for Logical Decoding</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-synchronous.html" title="47.8. Synchronous Replication Support for Logical Decoding">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-two-phase-commits.html" title="47.10. Two-phase Commit Support for Logical Decoding">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-STREAMING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">47.9. Streaming of Large Transactions for Logical Decoding <a href="#LOGICALDECODING-STREAMING" class="id_link">#</a></h2></div></div></div><p>
   3     The basic output plugin callbacks (e.g., <code class="function">begin_cb</code>,
   4     <code class="function">change_cb</code>, <code class="function">commit_cb</code> and
   5     <code class="function">message_cb</code>) are only invoked when the transaction
   6     actually commits. The changes are still decoded from the transaction
   7     log, but are only passed to the output plugin at commit (and discarded
   8     if the transaction aborts).
   9    </p><p>
  10     This means that while the decoding happens incrementally, and may spill
  11     to disk to keep memory usage under control, all the decoded changes have
  12     to be transmitted when the transaction finally commits (or more precisely,
  13     when the commit is decoded from the transaction log). Depending on the
  14     size of the transaction and network bandwidth, the transfer time may
  15     significantly increase the apply lag.
  16    </p><p>
  17     To reduce the apply lag caused by large transactions, an output plugin
  18     may provide additional callback to support incremental streaming of
  19     in-progress transactions. There are multiple required streaming callbacks
  20     (<code class="function">stream_start_cb</code>, <code class="function">stream_stop_cb</code>,
  21     <code class="function">stream_abort_cb</code>, <code class="function">stream_commit_cb</code>
  22     and <code class="function">stream_change_cb</code>) and two optional callbacks
  23     (<code class="function">stream_message_cb</code> and <code class="function">stream_truncate_cb</code>).
  24     Also, if streaming of two-phase commands is to be supported, then additional
  25     callbacks must be provided. (See <a class="xref" href="logicaldecoding-two-phase-commits.html" title="47.10. Two-phase Commit Support for Logical Decoding">Section 47.10</a>
  26     for details).
  27    </p><p>
  28     When streaming an in-progress transaction, the changes (and messages) are
  29     streamed in blocks demarcated by <code class="function">stream_start_cb</code>
  30     and <code class="function">stream_stop_cb</code> callbacks. Once all the decoded
  31     changes are transmitted, the transaction can be committed using the
  32     <code class="function">stream_commit_cb</code> callback
  33     (or possibly aborted using the <code class="function">stream_abort_cb</code> callback).
  34     If two-phase commits are supported, the transaction can be prepared using the
  35     <code class="function">stream_prepare_cb</code> callback,
  36     <code class="command">COMMIT PREPARED</code> using the
  37     <code class="function">commit_prepared_cb</code> callback or aborted using the
  38     <code class="function">rollback_prepared_cb</code>.
  39    </p><p>
  40     One example sequence of streaming callback calls for one transaction may
  41     look like this:
  42 </p><pre class="programlisting">
  43 stream_start_cb(...);   &lt;-- start of first block of changes
  44   stream_change_cb(...);
  45   stream_change_cb(...);
  46   stream_message_cb(...);
  47   stream_change_cb(...);
  48   ...
  49   stream_change_cb(...);
  50 stream_stop_cb(...);    &lt;-- end of first block of changes
  51
  52 stream_start_cb(...);   &lt;-- start of second block of changes
  53   stream_change_cb(...);
  54   stream_change_cb(...);
  55   stream_change_cb(...);
  56   ...
  57   stream_message_cb(...);
  58   stream_change_cb(...);
  59 stream_stop_cb(...);    &lt;-- end of second block of changes
  60
  61
  62 [a. when using normal commit]
  63 stream_commit_cb(...);    &lt;-- commit of the streamed transaction
  64
  65 [b. when using two-phase commit]
  66 stream_prepare_cb(...);   &lt;-- prepare the streamed transaction
  67 commit_prepared_cb(...);  &lt;-- commit of the prepared transaction
  68 </pre><p>
  69    </p><p>
  70     The actual sequence of callback calls may be more complicated, of course.
  71     There may be blocks for multiple streamed transactions, some of the
  72     transactions may get aborted, etc.
  73    </p><p>
  74     Similar to spill-to-disk behavior, streaming is triggered when the total
  75     amount of changes decoded from the WAL (for all in-progress transactions)
  76     exceeds the limit defined by <code class="varname">logical_decoding_work_mem</code> setting.
  77     At that point, the largest top-level transaction (measured by the amount of memory
  78     currently used for decoded changes) is selected and streamed.  However, in
  79     some cases we still have to spill to disk even if streaming is enabled
  80     because we exceed the memory threshold but still have not decoded the
  81     complete tuple e.g., only decoded toast table insert but not the main table
  82     insert.
  83    </p><p>
  84     Even when streaming large transactions, the changes are still applied in
  85     commit order, preserving the same guarantees as the non-streaming mode.
  86    </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-synchronous.html" title="47.8. Synchronous Replication Support for Logical Decoding">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-two-phase-commits.html" title="47.10. Two-phase Commit Support for Logical Decoding">Next</a></td></tr><tr><td width="40%" align="left" valign="top">47.8. Synchronous Replication Support for Logical Decoding </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.10. Two-phase Commit Support for Logical Decoding</td></tr></table></div></body></html>