begriffs open source - ai-pg/blob - full-docs/src/sgml/html/logicaldecoding-output-plugin.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.6. Logical Decoding Output Plugins</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-catalogs.html" title="47.5. System Catalogs Related to Logical Decoding" /><link rel="next" href="logicaldecoding-writer.html" title="47.7. Logical Decoding Output Writers" /></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.6. Logical Decoding Output Plugins</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-catalogs.html" title="47.5. System Catalogs Related to 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-writer.html" title="47.7. Logical Decoding Output Writers">Next</a></td></tr></table><hr /></div><div class="sect1" id="LOGICALDECODING-OUTPUT-PLUGIN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">47.6. Logical Decoding Output Plugins <a href="#LOGICALDECODING-OUTPUT-PLUGIN" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-INIT">47.6.1. Initialization Function</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-CAPABILITIES">47.6.2. Capabilities</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-MODE">47.6.3. Output Modes</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-CALLBACKS">47.6.4. Output Plugin Callbacks</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT">47.6.5. Functions for Producing Output</a></span></dt></dl></div><p>
   3     An example output plugin can be found in the
   4     <a class="link" href="test-decoding.html" title="F.45. test_decoding — SQL-based test/example module for WAL logical decoding">
   5      <code class="filename">contrib/test_decoding</code>
   6     </a>
   7     subdirectory of the PostgreSQL source tree.
   8    </p><div class="sect2" id="LOGICALDECODING-OUTPUT-INIT"><div class="titlepage"><div><div><h3 class="title">47.6.1. Initialization Function <a href="#LOGICALDECODING-OUTPUT-INIT" class="id_link">#</a></h3></div></div></div><a id="id-1.8.14.12.3.2" class="indexterm"></a><p>
   9      An output plugin is loaded by dynamically loading a shared library with
  10      the output plugin's name as the library base name. The normal library
  11      search path is used to locate the library. To provide the required output
  12      plugin callbacks and to indicate that the library is actually an output
  13      plugin it needs to provide a function named
  14      <code class="function">_PG_output_plugin_init</code>. This function is passed a
  15      struct that needs to be filled with the callback function pointers for
  16      individual actions.
  17 </p><pre class="programlisting">
  18 typedef struct OutputPluginCallbacks
  19 {
  20     LogicalDecodeStartupCB startup_cb;
  21     LogicalDecodeBeginCB begin_cb;
  22     LogicalDecodeChangeCB change_cb;
  23     LogicalDecodeTruncateCB truncate_cb;
  24     LogicalDecodeCommitCB commit_cb;
  25     LogicalDecodeMessageCB message_cb;
  26     LogicalDecodeFilterByOriginCB filter_by_origin_cb;
  27     LogicalDecodeShutdownCB shutdown_cb;
  28     LogicalDecodeFilterPrepareCB filter_prepare_cb;
  29     LogicalDecodeBeginPrepareCB begin_prepare_cb;
  30     LogicalDecodePrepareCB prepare_cb;
  31     LogicalDecodeCommitPreparedCB commit_prepared_cb;
  32     LogicalDecodeRollbackPreparedCB rollback_prepared_cb;
  33     LogicalDecodeStreamStartCB stream_start_cb;
  34     LogicalDecodeStreamStopCB stream_stop_cb;
  35     LogicalDecodeStreamAbortCB stream_abort_cb;
  36     LogicalDecodeStreamPrepareCB stream_prepare_cb;
  37     LogicalDecodeStreamCommitCB stream_commit_cb;
  38     LogicalDecodeStreamChangeCB stream_change_cb;
  39     LogicalDecodeStreamMessageCB stream_message_cb;
  40     LogicalDecodeStreamTruncateCB stream_truncate_cb;
  41 } OutputPluginCallbacks;
  42
  43 typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb);
  44 </pre><p>
  45      The <code class="function">begin_cb</code>, <code class="function">change_cb</code>
  46      and <code class="function">commit_cb</code> callbacks are required,
  47      while <code class="function">startup_cb</code>, <code class="function">truncate_cb</code>,
  48      <code class="function">message_cb</code>, <code class="function">filter_by_origin_cb</code>,
  49      and <code class="function">shutdown_cb</code> are optional.
  50      If <code class="function">truncate_cb</code> is not set but a
  51      <code class="command">TRUNCATE</code> is to be decoded, the action will be ignored.
  52     </p><p>
  53      An output plugin may also define functions to support streaming of large,
  54      in-progress transactions. The <code class="function">stream_start_cb</code>,
  55      <code class="function">stream_stop_cb</code>, <code class="function">stream_abort_cb</code>,
  56      <code class="function">stream_commit_cb</code>, and <code class="function">stream_change_cb</code>
  57      are required, while <code class="function">stream_message_cb</code> and
  58      <code class="function">stream_truncate_cb</code> are optional. The
  59      <code class="function">stream_prepare_cb</code> is also required if the output
  60      plugin also support two-phase commits.
  61     </p><p>
  62     An output plugin may also define functions to support two-phase commits,
  63     which allows actions to be decoded on the <code class="command">PREPARE TRANSACTION</code>.
  64     The <code class="function">begin_prepare_cb</code>, <code class="function">prepare_cb</code>,
  65     <code class="function">commit_prepared_cb</code> and <code class="function">rollback_prepared_cb</code>
  66     callbacks are required, while <code class="function">filter_prepare_cb</code> is optional.
  67     The <code class="function">stream_prepare_cb</code> is also required if the output plugin
  68     also supports the streaming of large in-progress transactions.
  69     </p></div><div class="sect2" id="LOGICALDECODING-CAPABILITIES"><div class="titlepage"><div><div><h3 class="title">47.6.2. Capabilities <a href="#LOGICALDECODING-CAPABILITIES" class="id_link">#</a></h3></div></div></div><p>
  70      To decode, format and output changes, output plugins can use most of the
  71      backend's normal infrastructure, including calling output functions. Read
  72      only access to relations is permitted as long as only relations are
  73      accessed that either have been created by <code class="command">initdb</code> in
  74      the <code class="literal">pg_catalog</code> schema, or have been marked as user
  75      provided catalog tables using
  76 </p><pre class="programlisting">
  77 ALTER TABLE user_catalog_table SET (user_catalog_table = true);
  78 CREATE TABLE another_catalog_table(data text) WITH (user_catalog_table = true);
  79 </pre><p>
  80      Note that access to user catalog tables or regular system catalog tables
  81      in the output plugins has to be done via the <code class="literal">systable_*</code>
  82      scan APIs only. Access via the <code class="literal">heap_*</code> scan APIs will
  83      error out. Additionally, any actions leading to transaction ID assignment
  84      are prohibited. That, among others, includes writing to tables, performing
  85      DDL changes, and calling <code class="literal">pg_current_xact_id()</code>.
  86     </p></div><div class="sect2" id="LOGICALDECODING-OUTPUT-MODE"><div class="titlepage"><div><div><h3 class="title">47.6.3. Output Modes <a href="#LOGICALDECODING-OUTPUT-MODE" class="id_link">#</a></h3></div></div></div><p>
  87      Output plugin callbacks can pass data to the consumer in nearly arbitrary
  88      formats. For some use cases, like viewing the changes via SQL, returning
  89      data in a data type that can contain arbitrary data (e.g., <code class="type">bytea</code>) is
  90      cumbersome. If the output plugin only outputs textual data in the
  91      server's encoding, it can declare that by
  92      setting <code class="literal">OutputPluginOptions.output_type</code>
  93      to <code class="literal">OUTPUT_PLUGIN_TEXTUAL_OUTPUT</code> instead
  94      of <code class="literal">OUTPUT_PLUGIN_BINARY_OUTPUT</code> in
  95      the <a class="link" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-STARTUP" title="47.6.4.1. Startup Callback">startup
  96      callback</a>. In that case, all the data has to be in the server's encoding
  97      so that a <code class="type">text</code> datum can contain it. This is checked in assertion-enabled
  98      builds.
  99     </p></div><div class="sect2" id="LOGICALDECODING-OUTPUT-PLUGIN-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">47.6.4. Output Plugin Callbacks <a href="#LOGICALDECODING-OUTPUT-PLUGIN-CALLBACKS" class="id_link">#</a></h3></div></div></div><p>
 100      An output plugin gets notified about changes that are happening via
 101      various callbacks it needs to provide.
 102     </p><p>
 103      Concurrent transactions are decoded in commit order, and only changes
 104      belonging to a specific transaction are decoded between
 105      the <code class="literal">begin</code> and <code class="literal">commit</code>
 106      callbacks. Transactions that were rolled back explicitly or implicitly
 107      never get
 108      decoded. Successful savepoints are
 109      folded into the transaction containing them in the order they were
 110      executed within that transaction. A transaction that is prepared for
 111      a two-phase commit using <code class="command">PREPARE TRANSACTION</code> will
 112      also be decoded if the output plugin callbacks needed for decoding
 113      them are provided. It is possible that the current prepared transaction
 114      which is being decoded is aborted concurrently via a
 115      <code class="command">ROLLBACK PREPARED</code> command. In that case, the logical
 116      decoding of this transaction will be aborted too. All the changes of such
 117      a transaction are skipped once the abort is detected and the
 118      <code class="function">prepare_cb</code> callback is invoked. Thus even in case of
 119      a concurrent abort, enough information is provided to the output plugin
 120      for it to properly deal with <code class="command">ROLLBACK PREPARED</code> once
 121      that is decoded.
 122     </p><div class="note"><h3 class="title">Note</h3><p>
 123       Only transactions that have already safely been flushed to disk will be
 124       decoded. That can lead to a <code class="command">COMMIT</code> not immediately being decoded in a
 125       directly following <code class="literal">pg_logical_slot_get_changes()</code>
 126       when <code class="varname">synchronous_commit</code> is set
 127       to <code class="literal">off</code>.
 128      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STARTUP"><div class="titlepage"><div><div><h4 class="title">47.6.4.1. Startup Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STARTUP" class="id_link">#</a></h4></div></div></div><p>
 129       The optional <code class="function">startup_cb</code> callback is called whenever
 130       a replication slot is created or asked to stream changes, independent
 131       of the number of changes that are ready to be put out.
 132 </p><pre class="programlisting">
 133 typedef void (*LogicalDecodeStartupCB) (struct LogicalDecodingContext *ctx,
 134                                         OutputPluginOptions *options,
 135                                         bool is_init);
 136 </pre><p>
 137       The <code class="literal">is_init</code> parameter will be true when the
 138       replication slot is being created and false
 139       otherwise. <em class="parameter"><code>options</code></em> points to a struct of options
 140       that output plugins can set:
 141 </p><pre class="programlisting">
 142 typedef struct OutputPluginOptions
 143 {
 144     OutputPluginOutputType output_type;
 145     bool        receive_rewrites;
 146 } OutputPluginOptions;
 147 </pre><p>
 148       <code class="literal">output_type</code> has to either be set to
 149       <code class="literal">OUTPUT_PLUGIN_TEXTUAL_OUTPUT</code>
 150       or <code class="literal">OUTPUT_PLUGIN_BINARY_OUTPUT</code>. See also
 151       <a class="xref" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-MODE" title="47.6.3. Output Modes">Section 47.6.3</a>.
 152       If <code class="literal">receive_rewrites</code> is true, the output plugin will
 153       also be called for changes made by heap rewrites during certain DDL
 154       operations.  These are of interest to plugins that handle DDL
 155       replication, but they require special handling.
 156      </p><p>
 157       The startup callback should validate the options present in
 158       <code class="literal">ctx-&gt;output_plugin_options</code>. If the output plugin
 159       needs to have a state, it can
 160       use <code class="literal">ctx-&gt;output_plugin_private</code> to store it.
 161      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-SHUTDOWN"><div class="titlepage"><div><div><h4 class="title">47.6.4.2. Shutdown Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-SHUTDOWN" class="id_link">#</a></h4></div></div></div><p>
 162       The optional <code class="function">shutdown_cb</code> callback is called
 163       whenever a formerly active replication slot is not used anymore and can
 164       be used to deallocate resources private to the output plugin. The slot
 165       isn't necessarily being dropped, streaming is just being stopped.
 166 </p><pre class="programlisting">
 167 typedef void (*LogicalDecodeShutdownCB) (struct LogicalDecodingContext *ctx);
 168 </pre><p>
 169      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-BEGIN"><div class="titlepage"><div><div><h4 class="title">47.6.4.3. Transaction Begin Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-BEGIN" class="id_link">#</a></h4></div></div></div><p>
 170       The required <code class="function">begin_cb</code> callback is called whenever a
 171       start of a committed transaction has been decoded. Aborted transactions
 172       and their contents never get decoded.
 173 </p><pre class="programlisting">
 174 typedef void (*LogicalDecodeBeginCB) (struct LogicalDecodingContext *ctx,
 175                                       ReorderBufferTXN *txn);
 176 </pre><p>
 177       The <em class="parameter"><code>txn</code></em> parameter contains meta information about
 178       the transaction, like the time stamp at which it has been committed and
 179       its XID.
 180      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-COMMIT"><div class="titlepage"><div><div><h4 class="title">47.6.4.4. Transaction End Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-COMMIT" class="id_link">#</a></h4></div></div></div><p>
 181       The required <code class="function">commit_cb</code> callback is called whenever
 182       a transaction commit has been
 183       decoded. The <code class="function">change_cb</code> callbacks for all modified
 184       rows will have been called before this, if there have been any modified
 185       rows.
 186 </p><pre class="programlisting">
 187 typedef void (*LogicalDecodeCommitCB) (struct LogicalDecodingContext *ctx,
 188                                        ReorderBufferTXN *txn,
 189                                        XLogRecPtr commit_lsn);
 190 </pre><p>
 191      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-CHANGE"><div class="titlepage"><div><div><h4 class="title">47.6.4.5. Change Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-CHANGE" class="id_link">#</a></h4></div></div></div><p>
 192       The required <code class="function">change_cb</code> callback is called for every
 193       individual row modification inside a transaction, may it be
 194       an <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
 195       or <code class="command">DELETE</code>. Even if the original command modified
 196       several rows at once the callback will be called individually for each
 197       row. The <code class="function">change_cb</code> callback may access system or
 198       user catalog tables to aid in the process of outputting the row
 199       modification details. In case of decoding a prepared (but yet
 200       uncommitted) transaction or decoding of an uncommitted transaction, this
 201       change callback might also error out due to simultaneous rollback of
 202       this very same transaction. In that case, the logical decoding of this
 203       aborted transaction is stopped gracefully.
 204 </p><pre class="programlisting">
 205 typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx,
 206                                        ReorderBufferTXN *txn,
 207                                        Relation relation,
 208                                        ReorderBufferChange *change);
 209 </pre><p>
 210       The <em class="parameter"><code>ctx</code></em> and <em class="parameter"><code>txn</code></em> parameters
 211       have the same contents as for the <code class="function">begin_cb</code>
 212       and <code class="function">commit_cb</code> callbacks, but additionally the
 213       relation descriptor <em class="parameter"><code>relation</code></em> points to the
 214       relation the row belongs to and a struct
 215       <em class="parameter"><code>change</code></em> describing the row modification are passed
 216       in.
 217      </p><div class="note"><h3 class="title">Note</h3><p>
 218        Only changes in user defined tables that are not unlogged
 219        (see <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-UNLOGGED"><code class="literal">UNLOGGED</code></a>) and not temporary
 220        (see <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-TEMPORARY"><code class="literal">TEMPORARY</code> or <code class="literal">TEMP</code></a>) can be extracted using
 221        logical decoding.
 222       </p></div></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-TRUNCATE"><div class="titlepage"><div><div><h4 class="title">47.6.4.6. Truncate Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-TRUNCATE" class="id_link">#</a></h4></div></div></div><p>
 223       The optional <code class="function">truncate_cb</code> callback is called for a
 224       <code class="command">TRUNCATE</code> command.
 225 </p><pre class="programlisting">
 226 typedef void (*LogicalDecodeTruncateCB) (struct LogicalDecodingContext *ctx,
 227                                          ReorderBufferTXN *txn,
 228                                          int nrelations,
 229                                          Relation relations[],
 230                                          ReorderBufferChange *change);
 231 </pre><p>
 232       The parameters are analogous to the <code class="function">change_cb</code>
 233       callback.  However, because <code class="command">TRUNCATE</code> actions on
 234       tables connected by foreign keys need to be executed together, this
 235       callback receives an array of relations instead of just a single one.
 236       See the description of the <a class="xref" href="sql-truncate.html" title="TRUNCATE"><span class="refentrytitle">TRUNCATE</span></a> statement for
 237       details.
 238      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-FILTER-ORIGIN"><div class="titlepage"><div><div><h4 class="title">47.6.4.7. Origin Filter Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-FILTER-ORIGIN" class="id_link">#</a></h4></div></div></div><p>
 239        The optional <code class="function">filter_by_origin_cb</code> callback
 240        is called to determine whether data that has been replayed
 241        from <em class="parameter"><code>origin_id</code></em> is of interest to the
 242        output plugin.
 243 </p><pre class="programlisting">
 244 typedef bool (*LogicalDecodeFilterByOriginCB) (struct LogicalDecodingContext *ctx,
 245                                                RepOriginId origin_id);
 246 </pre><p>
 247       The <em class="parameter"><code>ctx</code></em> parameter has the same contents
 248       as for the other callbacks. No information but the origin is
 249       available. To signal that changes originating on the passed in
 250       node are irrelevant, return true, causing them to be filtered
 251       away; false otherwise. The other callbacks will not be called
 252       for transactions and changes that have been filtered away.
 253      </p><p>
 254        This is useful when implementing cascading or multidirectional
 255        replication solutions. Filtering by the origin allows to
 256        prevent replicating the same changes back and forth in such
 257        setups.  While transactions and changes also carry information
 258        about the origin, filtering via this callback is noticeably
 259        more efficient.
 260      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-MESSAGE"><div class="titlepage"><div><div><h4 class="title">47.6.4.8. Generic Message Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-MESSAGE" class="id_link">#</a></h4></div></div></div><p>
 261       The optional <code class="function">message_cb</code> callback is called whenever
 262       a logical decoding message has been decoded.
 263 </p><pre class="programlisting">
 264 typedef void (*LogicalDecodeMessageCB) (struct LogicalDecodingContext *ctx,
 265                                         ReorderBufferTXN *txn,
 266                                         XLogRecPtr message_lsn,
 267                                         bool transactional,
 268                                         const char *prefix,
 269                                         Size message_size,
 270                                         const char *message);
 271 </pre><p>
 272       The <em class="parameter"><code>txn</code></em> parameter contains meta information about
 273       the transaction, like the time stamp at which it has been committed and
 274       its XID. Note however that it can be NULL when the message is
 275       non-transactional and the XID was not assigned yet in the transaction
 276       which logged the message. The <em class="parameter"><code>lsn</code></em> has WAL
 277       location of the message. The <em class="parameter"><code>transactional</code></em> says
 278       if the message was sent as transactional or not. Similar to the change
 279       callback, in case of decoding a prepared (but yet uncommitted)
 280       transaction or decoding of an uncommitted transaction, this message
 281       callback might also error out due to simultaneous rollback of
 282       this very same transaction. In that case, the logical decoding of this
 283       aborted transaction is stopped gracefully.
 284       The <em class="parameter"><code>prefix</code></em> is arbitrary null-terminated prefix
 285       which can be used for identifying interesting messages for the current
 286       plugin. And finally the <em class="parameter"><code>message</code></em> parameter holds
 287       the actual message of <em class="parameter"><code>message_size</code></em> size.
 288      </p><p>
 289       Extra care should be taken to ensure that the prefix the output plugin
 290       considers interesting is unique. Using name of the extension or the
 291       output plugin itself is often a good choice.
 292      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-FILTER-PREPARE"><div class="titlepage"><div><div><h4 class="title">47.6.4.9. Prepare Filter Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-FILTER-PREPARE" class="id_link">#</a></h4></div></div></div><p>
 293        The optional <code class="function">filter_prepare_cb</code> callback
 294        is called to determine whether data that is part of the current
 295        two-phase commit transaction should be considered for decoding
 296        at this prepare stage or later as a regular one-phase transaction at
 297        <code class="command">COMMIT PREPARED</code> time. To signal that
 298        decoding should be skipped, return <code class="literal">true</code>;
 299        <code class="literal">false</code> otherwise. When the callback is not
 300        defined, <code class="literal">false</code> is assumed (i.e. no filtering, all
 301        transactions using two-phase commit are decoded in two phases as well).
 302 </p><pre class="programlisting">
 303 typedef bool (*LogicalDecodeFilterPrepareCB) (struct LogicalDecodingContext *ctx,
 304                                               TransactionId xid,
 305                                               const char *gid);
 306 </pre><p>
 307        The <em class="parameter"><code>ctx</code></em> parameter has the same contents as for
 308        the other callbacks. The parameters <em class="parameter"><code>xid</code></em>
 309        and <em class="parameter"><code>gid</code></em> provide two different ways to identify
 310        the transaction.  The later <code class="command">COMMIT PREPARED</code> or
 311        <code class="command">ROLLBACK PREPARED</code> carries both identifiers,
 312        providing an output plugin the choice of what to use.
 313      </p><p>
 314        The callback may be invoked multiple times per transaction to decode
 315        and must provide the same static answer for a given pair of
 316        <em class="parameter"><code>xid</code></em> and <em class="parameter"><code>gid</code></em> every time
 317        it is called.
 318      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-BEGIN-PREPARE"><div class="titlepage"><div><div><h4 class="title">47.6.4.10. Transaction Begin Prepare Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-BEGIN-PREPARE" class="id_link">#</a></h4></div></div></div><p>
 319       The required <code class="function">begin_prepare_cb</code> callback is called
 320       whenever the start of a prepared transaction has been decoded. The
 321       <em class="parameter"><code>gid</code></em> field, which is part of the
 322       <em class="parameter"><code>txn</code></em> parameter, can be used in this callback to
 323       check if the plugin has already received this <code class="command">PREPARE</code>
 324       in which case it can either error out or skip the remaining changes of
 325       the transaction.
 326 </p><pre class="programlisting">
 327 typedef void (*LogicalDecodeBeginPrepareCB) (struct LogicalDecodingContext *ctx,
 328                                              ReorderBufferTXN *txn);
 329 </pre><p>
 330      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-PREPARE"><div class="titlepage"><div><div><h4 class="title">47.6.4.11. Transaction Prepare Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-PREPARE" class="id_link">#</a></h4></div></div></div><p>
 331       The required <code class="function">prepare_cb</code> callback is called whenever
 332       a transaction which is prepared for two-phase commit has been
 333       decoded. The <code class="function">change_cb</code> callback for all modified
 334       rows will have been called before this, if there have been any modified
 335       rows. The <em class="parameter"><code>gid</code></em> field, which is part of the
 336       <em class="parameter"><code>txn</code></em> parameter, can be used in this callback.
 337 </p><pre class="programlisting">
 338 typedef void (*LogicalDecodePrepareCB) (struct LogicalDecodingContext *ctx,
 339                                         ReorderBufferTXN *txn,
 340                                         XLogRecPtr prepare_lsn);
 341 </pre><p>
 342      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-COMMIT-PREPARED"><div class="titlepage"><div><div><h4 class="title">47.6.4.12. Transaction Commit Prepared Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-COMMIT-PREPARED" class="id_link">#</a></h4></div></div></div><p>
 343       The required <code class="function">commit_prepared_cb</code> callback is called
 344       whenever a transaction <code class="command">COMMIT PREPARED</code> has been decoded.
 345       The <em class="parameter"><code>gid</code></em> field, which is part of the
 346       <em class="parameter"><code>txn</code></em> parameter, can be used in this callback.
 347 </p><pre class="programlisting">
 348 typedef void (*LogicalDecodeCommitPreparedCB) (struct LogicalDecodingContext *ctx,
 349                                                ReorderBufferTXN *txn,
 350                                                XLogRecPtr commit_lsn);
 351 </pre><p>
 352      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-ROLLBACK-PREPARED"><div class="titlepage"><div><div><h4 class="title">47.6.4.13. Transaction Rollback Prepared Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-ROLLBACK-PREPARED" class="id_link">#</a></h4></div></div></div><p>
 353       The required <code class="function">rollback_prepared_cb</code> callback is called
 354       whenever a transaction <code class="command">ROLLBACK PREPARED</code> has been
 355       decoded. The <em class="parameter"><code>gid</code></em> field, which is part of the
 356       <em class="parameter"><code>txn</code></em> parameter, can be used in this callback. The
 357       parameters <em class="parameter"><code>prepare_end_lsn</code></em> and
 358       <em class="parameter"><code>prepare_time</code></em> can be used to check if the plugin
 359       has received this <code class="command">PREPARE TRANSACTION</code> in which case
 360       it can apply the rollback, otherwise, it can skip the rollback operation. The
 361       <em class="parameter"><code>gid</code></em> alone is not sufficient because the downstream
 362       node can have a prepared transaction with same identifier.
 363 </p><pre class="programlisting">
 364 typedef void (*LogicalDecodeRollbackPreparedCB) (struct LogicalDecodingContext *ctx,
 365                                                  ReorderBufferTXN *txn,
 366                                                  XLogRecPtr prepare_end_lsn,
 367                                                  TimestampTz prepare_time);
 368 </pre><p>
 369      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-START"><div class="titlepage"><div><div><h4 class="title">47.6.4.14. Stream Start Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-START" class="id_link">#</a></h4></div></div></div><p>
 370       The required <code class="function">stream_start_cb</code> callback is called when
 371       opening a block of streamed changes from an in-progress transaction.
 372 </p><pre class="programlisting">
 373 typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
 374                                             ReorderBufferTXN *txn);
 375 </pre><p>
 376      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-STOP"><div class="titlepage"><div><div><h4 class="title">47.6.4.15. Stream Stop Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-STOP" class="id_link">#</a></h4></div></div></div><p>
 377       The required <code class="function">stream_stop_cb</code> callback is called when
 378       closing a block of streamed changes from an in-progress transaction.
 379 </p><pre class="programlisting">
 380 typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
 381                                            ReorderBufferTXN *txn);
 382 </pre><p>
 383      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-ABORT"><div class="titlepage"><div><div><h4 class="title">47.6.4.16. Stream Abort Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-ABORT" class="id_link">#</a></h4></div></div></div><p>
 384       The required <code class="function">stream_abort_cb</code> callback is called to
 385       abort a previously streamed transaction.
 386 </p><pre class="programlisting">
 387 typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
 388                                             ReorderBufferTXN *txn,
 389                                             XLogRecPtr abort_lsn);
 390 </pre><p>
 391      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-PREPARE"><div class="titlepage"><div><div><h4 class="title">47.6.4.17. Stream Prepare Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-PREPARE" class="id_link">#</a></h4></div></div></div><p>
 392       The <code class="function">stream_prepare_cb</code> callback is called to prepare
 393       a previously streamed transaction as part of a two-phase commit. This
 394       callback is required when the output plugin supports both the streaming
 395       of large in-progress transactions and two-phase commits.
 396       </p><pre class="programlisting">
 397 typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx,
 398                                               ReorderBufferTXN *txn,
 399                                               XLogRecPtr prepare_lsn);
 400 </pre><p>
 401      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-COMMIT"><div class="titlepage"><div><div><h4 class="title">47.6.4.18. Stream Commit Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-COMMIT" class="id_link">#</a></h4></div></div></div><p>
 402       The required <code class="function">stream_commit_cb</code> callback is called to
 403       commit a previously streamed transaction.
 404 </p><pre class="programlisting">
 405 typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
 406                                              ReorderBufferTXN *txn,
 407                                              XLogRecPtr commit_lsn);
 408 </pre><p>
 409      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-CHANGE"><div class="titlepage"><div><div><h4 class="title">47.6.4.19. Stream Change Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-CHANGE" class="id_link">#</a></h4></div></div></div><p>
 410       The required <code class="function">stream_change_cb</code> callback is called
 411       when sending a change in a block of streamed changes (demarcated by
 412       <code class="function">stream_start_cb</code> and <code class="function">stream_stop_cb</code> calls).
 413       The actual changes are not displayed as the transaction can abort at a later
 414       point in time and we don't decode changes for aborted transactions.
 415 </p><pre class="programlisting">
 416 typedef void (*LogicalDecodeStreamChangeCB) (struct LogicalDecodingContext *ctx,
 417                                              ReorderBufferTXN *txn,
 418                                              Relation relation,
 419                                              ReorderBufferChange *change);
 420 </pre><p>
 421      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-MESSAGE"><div class="titlepage"><div><div><h4 class="title">47.6.4.20. Stream Message Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-MESSAGE" class="id_link">#</a></h4></div></div></div><p>
 422       The optional <code class="function">stream_message_cb</code> callback is called when
 423       sending a generic message in a block of streamed changes (demarcated by
 424       <code class="function">stream_start_cb</code> and <code class="function">stream_stop_cb</code> calls).
 425       The message contents for transactional messages are not displayed as the transaction
 426       can abort at a later point in time and we don't decode changes for aborted
 427       transactions.
 428 </p><pre class="programlisting">
 429 typedef void (*LogicalDecodeStreamMessageCB) (struct LogicalDecodingContext *ctx,
 430                                               ReorderBufferTXN *txn,
 431                                               XLogRecPtr message_lsn,
 432                                               bool transactional,
 433                                               const char *prefix,
 434                                               Size message_size,
 435                                               const char *message);
 436 </pre><p>
 437      </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-TRUNCATE"><div class="titlepage"><div><div><h4 class="title">47.6.4.21. Stream Truncate Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-TRUNCATE" class="id_link">#</a></h4></div></div></div><p>
 438       The optional <code class="function">stream_truncate_cb</code> callback is called
 439       for a <code class="command">TRUNCATE</code> command in a block of streamed changes
 440       (demarcated by <code class="function">stream_start_cb</code> and
 441       <code class="function">stream_stop_cb</code> calls).
 442 </p><pre class="programlisting">
 443 typedef void (*LogicalDecodeStreamTruncateCB) (struct LogicalDecodingContext *ctx,
 444                                                ReorderBufferTXN *txn,
 445                                                int nrelations,
 446                                                Relation relations[],
 447                                                ReorderBufferChange *change);
 448 </pre><p>
 449       The parameters are analogous to the <code class="function">stream_change_cb</code>
 450       callback.  However, because <code class="command">TRUNCATE</code> actions on
 451       tables connected by foreign keys need to be executed together, this
 452       callback receives an array of relations instead of just a single one.
 453       See the description of the <a class="xref" href="sql-truncate.html" title="TRUNCATE"><span class="refentrytitle">TRUNCATE</span></a> statement for
 454       details.
 455      </p></div></div><div class="sect2" id="LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT"><div class="titlepage"><div><div><h3 class="title">47.6.5. Functions for Producing Output <a href="#LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT" class="id_link">#</a></h3></div></div></div><p>
 456      To actually produce output, output plugins can write data to
 457      the <code class="literal">StringInfo</code> output buffer
 458      in <code class="literal">ctx-&gt;out</code> when inside
 459      the <code class="function">begin_cb</code>, <code class="function">commit_cb</code>,
 460      or <code class="function">change_cb</code> callbacks. Before writing to the output
 461      buffer, <code class="function">OutputPluginPrepareWrite(ctx, last_write)</code> has
 462      to be called, and after finishing writing to the
 463      buffer, <code class="function">OutputPluginWrite(ctx, last_write)</code> has to be
 464      called to perform the write. The <em class="parameter"><code>last_write</code></em>
 465      indicates whether a particular write was the callback's last write.
 466     </p><p>
 467      The following example shows how to output data to the consumer of an
 468      output plugin:
 469 </p><pre class="programlisting">
 470 OutputPluginPrepareWrite(ctx, true);
 471 appendStringInfo(ctx-&gt;out, "BEGIN %u", txn-&gt;xid);
 472 OutputPluginWrite(ctx, true);
 473 </pre><p>
 474     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-catalogs.html" title="47.5. System Catalogs Related to 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-writer.html" title="47.7. Logical Decoding Output Writers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">47.5. System Catalogs Related to 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.7. Logical Decoding Output Writers</td></tr></table></div></body></html>