codekingpro/portable-devtools
115k
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->output_plugin_options</code>. If the output plugin159 needs to have a state, it can160 use <code class="literal">ctx->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->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->out, "BEGIN %u", txn->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>