Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes15kdownloads
logicaldecoding-output-plugin.html475 linesDownload Raw Back to 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>49.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="49.5. System Catalogs Related to Logical Decoding" /><link rel="next" href="logicaldecoding-writer.html" title="49.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">49.6. Logical Decoding Output Plugins</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-catalogs.html" title="49.5. System Catalogs Related to Logical Decoding">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><th width="60%" align="center">Chapter 49. Logical Decoding</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="logicaldecoding-writer.html" title="49.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">49.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">49.6.1. Initialization Function</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-CAPABILITIES">49.6.2. Capabilities</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-MODE">49.6.3. Output Modes</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-CALLBACKS">49.6.4. Output Plugin Callbacks</a></span></dt><dt><span class="sect2"><a href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT">49.6.5. Functions for Producing Output</a></span></dt></dl></div><p>3    An example output plugin can be found in the4    <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">49.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 with10     the output plugin's name as the library base name. The normal library11     search path is used to locate the library. To provide the required output12     plugin callbacks and to indicate that the library is actually an output13     plugin it needs to provide a function named14     <code class="function">_PG_output_plugin_init</code>. This function is passed a15     struct that needs to be filled with the callback function pointers for16     individual actions.17</p><pre class="programlisting">18typedef struct OutputPluginCallbacks19{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 43typedef 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 a51     <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> and58     <code class="function">stream_truncate_cb</code> are optional. The59     <code class="function">stream_prepare_cb</code> is also required if the output60     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 plugin68    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">49.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 the71     backend's normal infrastructure, including calling output functions. Read72     only access to relations is permitted as long as only relations are73     accessed that either have been created by <code class="command">initdb</code> in74     the <code class="literal">pg_catalog</code> schema, or have been marked as user75     provided catalog tables using76</p><pre class="programlisting">77ALTER TABLE user_catalog_table SET (user_catalog_table = true);78CREATE 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 tables81     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 will83     error out. Additionally, any actions leading to transaction ID assignment84     are prohibited. That, among others, includes writing to tables, performing85     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">49.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 arbitrary88     formats. For some use cases, like viewing the changes via SQL, returning89     data in a data type that can contain arbitrary data (e.g., <code class="type">bytea</code>) is90     cumbersome. If the output plugin only outputs textual data in the91     server's encoding, it can declare that by92     setting <code class="literal">OutputPluginOptions.output_type</code>93     to <code class="literal">OUTPUT_PLUGIN_TEXTUAL_OUTPUT</code> instead94     of <code class="literal">OUTPUT_PLUGIN_BINARY_OUTPUT</code> in95     the <a class="link" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-STARTUP" title="49.6.4.1. Startup Callback">startup96     callback</a>. In that case, all the data has to be in the server's encoding97     so that a <code class="type">text</code> datum can contain it. This is checked in assertion-enabled98     builds.99    </p></div><div class="sect2" id="LOGICALDECODING-OUTPUT-PLUGIN-CALLBACKS"><div class="titlepage"><div><div><h3 class="title">49.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 via101     various callbacks it needs to provide.102    </p><p>103     Concurrent transactions are decoded in commit order, and only changes104     belonging to a specific transaction are decoded between105     the <code class="literal">begin</code> and <code class="literal">commit</code>106     callbacks. Transactions that were rolled back explicitly or implicitly107     never get108     decoded. Successful savepoints are109     folded into the transaction containing them in the order they were110     executed within that transaction. A transaction that is prepared for111     a two-phase commit using <code class="command">PREPARE TRANSACTION</code> will112     also be decoded if the output plugin callbacks needed for decoding113     them are provided. It is possible that the current prepared transaction114     which is being decoded is aborted concurrently via a115     <code class="command">ROLLBACK PREPARED</code> command. In that case, the logical116     decoding of this transaction will be aborted too. All the changes of such117     a transaction are skipped once the abort is detected and the118     <code class="function">prepare_cb</code> callback is invoked. Thus even in case of119     a concurrent abort, enough information is provided to the output plugin120     for it to properly deal with <code class="command">ROLLBACK PREPARED</code> once121     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 be124      decoded. That can lead to a <code class="command">COMMIT</code> not immediately being decoded in a125      directly following <code class="literal">pg_logical_slot_get_changes()</code>126      when <code class="varname">synchronous_commit</code> is set127      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">49.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 whenever130      a replication slot is created or asked to stream changes, independent131      of the number of changes that are ready to be put out.132</p><pre class="programlisting">133typedef 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 the138      replication slot is being created and false139      otherwise. <em class="parameter"><code>options</code></em> points to a struct of options140      that output plugins can set:141</p><pre class="programlisting">142typedef struct OutputPluginOptions143{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 to149      <code class="literal">OUTPUT_PLUGIN_TEXTUAL_OUTPUT</code>150      or <code class="literal">OUTPUT_PLUGIN_BINARY_OUTPUT</code>. See also151      <a class="xref" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-MODE" title="49.6.3. Output Modes">Section 49.6.3</a>.152      If <code class="literal">receive_rewrites</code> is true, the output plugin will153      also be called for changes made by heap rewrites during certain DDL154      operations.  These are of interest to plugins that handle DDL155      replication, but they require special handling.156     </p><p>157      The startup callback should validate the options present in158      <code class="literal">ctx-&gt;output_plugin_options</code>. If the output plugin159      needs to have a state, it can160      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">49.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 called163      whenever a formerly active replication slot is not used anymore and can164      be used to deallocate resources private to the output plugin. The slot165      isn't necessarily being dropped, streaming is just being stopped.166</p><pre class="programlisting">167typedef 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">49.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 a171      start of a committed transaction has been decoded. Aborted transactions172      and their contents never get decoded.173</p><pre class="programlisting">174typedef void (*LogicalDecodeBeginCB) (struct LogicalDecodingContext *ctx,175                                      ReorderBufferTXN *txn);176</pre><p>177      The <em class="parameter"><code>txn</code></em> parameter contains meta information about178      the transaction, like the time stamp at which it has been committed and179      its XID.180     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-COMMIT"><div class="titlepage"><div><div><h4 class="title">49.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 whenever182      a transaction commit has been183      decoded. The <code class="function">change_cb</code> callbacks for all modified184      rows will have been called before this, if there have been any modified185      rows.186</p><pre class="programlisting">187typedef 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">49.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 every193      individual row modification inside a transaction, may it be194      an <code class="command">INSERT</code>, <code class="command">UPDATE</code>,195      or <code class="command">DELETE</code>. Even if the original command modified196      several rows at once the callback will be called individually for each197      row. The <code class="function">change_cb</code> callback may access system or198      user catalog tables to aid in the process of outputting the row199      modification details. In case of decoding a prepared (but yet200      uncommitted) transaction or decoding of an uncommitted transaction, this201      change callback might also error out due to simultaneous rollback of202      this very same transaction. In that case, the logical decoding of this203      aborted transaction is stopped gracefully.204</p><pre class="programlisting">205typedef 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> parameters211      have the same contents as for the <code class="function">begin_cb</code>212      and <code class="function">commit_cb</code> callbacks, but additionally the213      relation descriptor <em class="parameter"><code>relation</code></em> points to the214      relation the row belongs to and a struct215      <em class="parameter"><code>change</code></em> describing the row modification are passed216      in.217     </p><div class="note"><h3 class="title">Note</h3><p>218       Only changes in user defined tables that are not unlogged219       (see <a class="xref" href="sql-createtable.html#SQL-CREATETABLE-UNLOGGED"><code class="literal">UNLOGGED</code></a>) and not temporary220       (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 using221       logical decoding.222      </p></div></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-TRUNCATE"><div class="titlepage"><div><div><h4 class="title">49.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 a224      <code class="command">TRUNCATE</code> command.225</p><pre class="programlisting">226typedef 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 on234      tables connected by foreign keys need to be executed together, this235      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 for237      details.238     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-FILTER-ORIGIN"><div class="titlepage"><div><div><h4 class="title">49.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> callback240       is called to determine whether data that has been replayed241       from <em class="parameter"><code>origin_id</code></em> is of interest to the242       output plugin.243</p><pre class="programlisting">244typedef 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 contents248      as for the other callbacks. No information but the origin is249      available. To signal that changes originating on the passed in250      node are irrelevant, return true, causing them to be filtered251      away; false otherwise. The other callbacks will not be called252      for transactions and changes that have been filtered away.253     </p><p>254       This is useful when implementing cascading or multidirectional255       replication solutions. Filtering by the origin allows to256       prevent replicating the same changes back and forth in such257       setups.  While transactions and changes also carry information258       about the origin, filtering via this callback is noticeably259       more efficient.260     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-MESSAGE"><div class="titlepage"><div><div><h4 class="title">49.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 whenever262      a logical decoding message has been decoded.263</p><pre class="programlisting">264typedef 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 about273      the transaction, like the time stamp at which it has been committed and274      its XID. Note however that it can be NULL when the message is275      non-transactional and the XID was not assigned yet in the transaction276      which logged the message. The <em class="parameter"><code>lsn</code></em> has WAL277      location of the message. The <em class="parameter"><code>transactional</code></em> says278      if the message was sent as transactional or not. Similar to the change279      callback, in case of decoding a prepared (but yet uncommitted)280      transaction or decoding of an uncommitted transaction, this message281      callback might also error out due to simultaneous rollback of282      this very same transaction. In that case, the logical decoding of this283      aborted transaction is stopped gracefully.284 285      The <em class="parameter"><code>prefix</code></em> is arbitrary null-terminated prefix286      which can be used for identifying interesting messages for the current287      plugin. And finally the <em class="parameter"><code>message</code></em> parameter holds288      the actual message of <em class="parameter"><code>message_size</code></em> size.289     </p><p>290      Extra care should be taken to ensure that the prefix the output plugin291      considers interesting is unique. Using name of the extension or the292      output plugin itself is often a good choice.293     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-FILTER-PREPARE"><div class="titlepage"><div><div><h4 class="title">49.6.4.9. Prepare Filter Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-FILTER-PREPARE" class="id_link">#</a></h4></div></div></div><p>294       The optional <code class="function">filter_prepare_cb</code> callback295       is called to determine whether data that is part of the current296       two-phase commit transaction should be considered for decoding297       at this prepare stage or later as a regular one-phase transaction at298       <code class="command">COMMIT PREPARED</code> time. To signal that299       decoding should be skipped, return <code class="literal">true</code>;300       <code class="literal">false</code> otherwise. When the callback is not301       defined, <code class="literal">false</code> is assumed (i.e. no filtering, all302       transactions using two-phase commit are decoded in two phases as well).303</p><pre class="programlisting">304typedef bool (*LogicalDecodeFilterPrepareCB) (struct LogicalDecodingContext *ctx,305                                              TransactionId xid,306                                              const char *gid);307</pre><p>308       The <em class="parameter"><code>ctx</code></em> parameter has the same contents as for309       the other callbacks. The parameters <em class="parameter"><code>xid</code></em>310       and <em class="parameter"><code>gid</code></em> provide two different ways to identify311       the transaction.  The later <code class="command">COMMIT PREPARED</code> or312       <code class="command">ROLLBACK PREPARED</code> carries both identifiers,313       providing an output plugin the choice of what to use.314     </p><p>315       The callback may be invoked multiple times per transaction to decode316       and must provide the same static answer for a given pair of317       <em class="parameter"><code>xid</code></em> and <em class="parameter"><code>gid</code></em> every time318       it is called.319     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-BEGIN-PREPARE"><div class="titlepage"><div><div><h4 class="title">49.6.4.10. Transaction Begin Prepare Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-BEGIN-PREPARE" class="id_link">#</a></h4></div></div></div><p>320      The required <code class="function">begin_prepare_cb</code> callback is called321      whenever the start of a prepared transaction has been decoded. The322      <em class="parameter"><code>gid</code></em> field, which is part of the323      <em class="parameter"><code>txn</code></em> parameter, can be used in this callback to324      check if the plugin has already received this <code class="command">PREPARE</code>325      in which case it can either error out or skip the remaining changes of326      the transaction.327</p><pre class="programlisting">328typedef void (*LogicalDecodeBeginPrepareCB) (struct LogicalDecodingContext *ctx,329                                             ReorderBufferTXN *txn);330</pre><p>331     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-PREPARE"><div class="titlepage"><div><div><h4 class="title">49.6.4.11. Transaction Prepare Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-PREPARE" class="id_link">#</a></h4></div></div></div><p>332      The required <code class="function">prepare_cb</code> callback is called whenever333      a transaction which is prepared for two-phase commit has been334      decoded. The <code class="function">change_cb</code> callback for all modified335      rows will have been called before this, if there have been any modified336      rows. The <em class="parameter"><code>gid</code></em> field, which is part of the337      <em class="parameter"><code>txn</code></em> parameter, can be used in this callback.338</p><pre class="programlisting">339typedef void (*LogicalDecodePrepareCB) (struct LogicalDecodingContext *ctx,340                                        ReorderBufferTXN *txn,341                                        XLogRecPtr prepare_lsn);342</pre><p>343     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-COMMIT-PREPARED"><div class="titlepage"><div><div><h4 class="title">49.6.4.12. Transaction Commit Prepared Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-COMMIT-PREPARED" class="id_link">#</a></h4></div></div></div><p>344      The required <code class="function">commit_prepared_cb</code> callback is called345      whenever a transaction <code class="command">COMMIT PREPARED</code> has been decoded.346      The <em class="parameter"><code>gid</code></em> field, which is part of the347      <em class="parameter"><code>txn</code></em> parameter, can be used in this callback.348</p><pre class="programlisting">349typedef void (*LogicalDecodeCommitPreparedCB) (struct LogicalDecodingContext *ctx,350                                               ReorderBufferTXN *txn,351                                               XLogRecPtr commit_lsn);352</pre><p>353     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-ROLLBACK-PREPARED"><div class="titlepage"><div><div><h4 class="title">49.6.4.13. Transaction Rollback Prepared Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-ROLLBACK-PREPARED" class="id_link">#</a></h4></div></div></div><p>354      The required <code class="function">rollback_prepared_cb</code> callback is called355      whenever a transaction <code class="command">ROLLBACK PREPARED</code> has been356      decoded. The <em class="parameter"><code>gid</code></em> field, which is part of the357      <em class="parameter"><code>txn</code></em> parameter, can be used in this callback. The358      parameters <em class="parameter"><code>prepare_end_lsn</code></em> and359      <em class="parameter"><code>prepare_time</code></em> can be used to check if the plugin360      has received this <code class="command">PREPARE TRANSACTION</code> in which case361      it can apply the rollback, otherwise, it can skip the rollback operation. The362      <em class="parameter"><code>gid</code></em> alone is not sufficient because the downstream363      node can have a prepared transaction with same identifier.364</p><pre class="programlisting">365typedef void (*LogicalDecodeRollbackPreparedCB) (struct LogicalDecodingContext *ctx,366                                                 ReorderBufferTXN *txn,367                                                 XLogRecPtr prepare_end_lsn,368                                                 TimestampTz prepare_time);369</pre><p>370     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-START"><div class="titlepage"><div><div><h4 class="title">49.6.4.14. Stream Start Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-START" class="id_link">#</a></h4></div></div></div><p>371      The required <code class="function">stream_start_cb</code> callback is called when372      opening a block of streamed changes from an in-progress transaction.373</p><pre class="programlisting">374typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,375                                            ReorderBufferTXN *txn);376</pre><p>377     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-STOP"><div class="titlepage"><div><div><h4 class="title">49.6.4.15. Stream Stop Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-STOP" class="id_link">#</a></h4></div></div></div><p>378      The required <code class="function">stream_stop_cb</code> callback is called when379      closing a block of streamed changes from an in-progress transaction.380</p><pre class="programlisting">381typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,382                                           ReorderBufferTXN *txn);383</pre><p>384     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-ABORT"><div class="titlepage"><div><div><h4 class="title">49.6.4.16. Stream Abort Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-ABORT" class="id_link">#</a></h4></div></div></div><p>385      The required <code class="function">stream_abort_cb</code> callback is called to386      abort a previously streamed transaction.387</p><pre class="programlisting">388typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,389                                            ReorderBufferTXN *txn,390                                            XLogRecPtr abort_lsn);391</pre><p>392     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-PREPARE"><div class="titlepage"><div><div><h4 class="title">49.6.4.17. Stream Prepare Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-PREPARE" class="id_link">#</a></h4></div></div></div><p>393      The <code class="function">stream_prepare_cb</code> callback is called to prepare394      a previously streamed transaction as part of a two-phase commit. This395      callback is required when the output plugin supports both the streaming396      of large in-progress transactions and two-phase commits.397      </p><pre class="programlisting">398typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx,399                                              ReorderBufferTXN *txn,400                                              XLogRecPtr prepare_lsn);401</pre><p>402     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-COMMIT"><div class="titlepage"><div><div><h4 class="title">49.6.4.18. Stream Commit Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-COMMIT" class="id_link">#</a></h4></div></div></div><p>403      The required <code class="function">stream_commit_cb</code> callback is called to404      commit a previously streamed transaction.405</p><pre class="programlisting">406typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,407                                             ReorderBufferTXN *txn,408                                             XLogRecPtr commit_lsn);409</pre><p>410     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-CHANGE"><div class="titlepage"><div><div><h4 class="title">49.6.4.19. Stream Change Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-CHANGE" class="id_link">#</a></h4></div></div></div><p>411      The required <code class="function">stream_change_cb</code> callback is called412      when sending a change in a block of streamed changes (demarcated by413      <code class="function">stream_start_cb</code> and <code class="function">stream_stop_cb</code> calls).414      The actual changes are not displayed as the transaction can abort at a later415      point in time and we don't decode changes for aborted transactions.416</p><pre class="programlisting">417typedef void (*LogicalDecodeStreamChangeCB) (struct LogicalDecodingContext *ctx,418                                             ReorderBufferTXN *txn,419                                             Relation relation,420                                             ReorderBufferChange *change);421</pre><p>422     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-MESSAGE"><div class="titlepage"><div><div><h4 class="title">49.6.4.20. Stream Message Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-MESSAGE" class="id_link">#</a></h4></div></div></div><p>423      The optional <code class="function">stream_message_cb</code> callback is called when424      sending a generic message in a block of streamed changes (demarcated by425      <code class="function">stream_start_cb</code> and <code class="function">stream_stop_cb</code> calls).426      The message contents for transactional messages are not displayed as the transaction427      can abort at a later point in time and we don't decode changes for aborted428      transactions.429</p><pre class="programlisting">430typedef void (*LogicalDecodeStreamMessageCB) (struct LogicalDecodingContext *ctx,431                                              ReorderBufferTXN *txn,432                                              XLogRecPtr message_lsn,433                                              bool transactional,434                                              const char *prefix,435                                              Size message_size,436                                              const char *message);437</pre><p>438     </p></div><div class="sect3" id="LOGICALDECODING-OUTPUT-PLUGIN-STREAM-TRUNCATE"><div class="titlepage"><div><div><h4 class="title">49.6.4.21. Stream Truncate Callback <a href="#LOGICALDECODING-OUTPUT-PLUGIN-STREAM-TRUNCATE" class="id_link">#</a></h4></div></div></div><p>439      The optional <code class="function">stream_truncate_cb</code> callback is called440      for a <code class="command">TRUNCATE</code> command in a block of streamed changes441      (demarcated by <code class="function">stream_start_cb</code> and442      <code class="function">stream_stop_cb</code> calls).443</p><pre class="programlisting">444typedef void (*LogicalDecodeStreamTruncateCB) (struct LogicalDecodingContext *ctx,445                                               ReorderBufferTXN *txn,446                                               int nrelations,447                                               Relation relations[],448                                               ReorderBufferChange *change);449</pre><p>450      The parameters are analogous to the <code class="function">stream_change_cb</code>451      callback.  However, because <code class="command">TRUNCATE</code> actions on452      tables connected by foreign keys need to be executed together, this453      callback receives an array of relations instead of just a single one.454      See the description of the <a class="xref" href="sql-truncate.html" title="TRUNCATE"><span class="refentrytitle">TRUNCATE</span></a> statement for455      details.456     </p></div></div><div class="sect2" id="LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT"><div class="titlepage"><div><div><h3 class="title">49.6.5. Functions for Producing Output <a href="#LOGICALDECODING-OUTPUT-PLUGIN-OUTPUT" class="id_link">#</a></h3></div></div></div><p>457     To actually produce output, output plugins can write data to458     the <code class="literal">StringInfo</code> output buffer459     in <code class="literal">ctx-&gt;out</code> when inside460     the <code class="function">begin_cb</code>, <code class="function">commit_cb</code>,461     or <code class="function">change_cb</code> callbacks. Before writing to the output462     buffer, <code class="function">OutputPluginPrepareWrite(ctx, last_write)</code> has463     to be called, and after finishing writing to the464     buffer, <code class="function">OutputPluginWrite(ctx, last_write)</code> has to be465     called to perform the write. The <em class="parameter"><code>last_write</code></em>466     indicates whether a particular write was the callback's last write.467    </p><p>468     The following example shows how to output data to the consumer of an469     output plugin:470</p><pre class="programlisting">471OutputPluginPrepareWrite(ctx, true);472appendStringInfo(ctx-&gt;out, "BEGIN %u", txn-&gt;xid);473OutputPluginWrite(ctx, true);474</pre><p>475    </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="49.5. System Catalogs Related to Logical Decoding">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="logicaldecoding-writer.html" title="49.7. Logical Decoding Output Writers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.5. System Catalogs Related to Logical Decoding </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 49.7. Logical Decoding Output Writers</td></tr></table></div></body></html>
codekingpro/portable-devtools · Team Ai