1 files changed, 68 insertions, 0 deletions
diff --git a/doc/src/sgml/html/replication-origins.html b/doc/src/sgml/html/replication-origins.html
new file mode 100644
index 0000000..502b48e
--- /dev/null
+++ b/doc/src/sgml/html/replication-origins.html
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!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>Chapter 50. Replication Progress Tracking</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-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding" /><link rel="next" href="archive-modules.html" title="Chapter 51. Archive Modules" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 50. Replication Progress Tracking</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="logicaldecoding-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><th width="60%" align="center">Part V. Server Programming</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="archive-modules.html" title="Chapter 51. Archive Modules">Next</a></td></tr></table><hr /></div><div class="chapter" id="REPLICATION-ORIGINS"><div class="titlepage"><div><div><h2 class="title">Chapter 50. Replication Progress Tracking</h2></div></div></div><a id="id-1.8.15.2" class="indexterm"></a><a id="id-1.8.15.3" class="indexterm"></a><p>
+  Replication origins are intended to make it easier to implement
+  logical replication solutions on top
+  of <a class="link" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">logical decoding</a>.
+  They provide a solution to two common problems:
+  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>How to safely keep track of replication progress</p></li><li class="listitem"><p>How to change replication behavior based on the
+     origin of a row; for example, to prevent loops in bi-directional
+     replication setups</p></li></ul></div><p>
+ </p><p>
+  Replication origins have just two properties, a name and an ID. The name,
+  which is what should be used to refer to the origin across systems, is
+  free-form <code class="type">text</code>. It should be used in a way that makes conflicts
+  between replication origins created by different replication solutions
+  unlikely; e.g., by prefixing the replication solution's name to it.
+  The ID is used only to avoid having to store the long version
+  in situations where space efficiency is important. It should never be shared
+  across systems.
+ </p><p>
+  Replication origins can be created using the function
+  <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-CREATE"><code class="function">pg_replication_origin_create()</code></a>;
+  dropped using
+  <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-DROP"><code class="function">pg_replication_origin_drop()</code></a>;
+  and seen in the
+  <a class="link" href="catalog-pg-replication-origin.html" title="53.44. pg_replication_origin"><code class="structname">pg_replication_origin</code></a>
+  system catalog.
+ </p><p>
+  One nontrivial part of building a replication solution is to keep track of
+  replay progress in a safe manner. When the applying process, or the whole
+  cluster, dies, it needs to be possible to find out up to where data has
+  successfully been replicated. Naive solutions to this, such as updating a
+  row in a table for every replayed transaction, have problems like run-time
+  overhead and database bloat.
+ </p><p>
+  Using the replication origin infrastructure a session can be
+  marked as replaying from a remote node (using the
+  <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-SESSION-SETUP"><code class="function">pg_replication_origin_session_setup()</code></a>
+  function). Additionally the <acronym class="acronym">LSN</acronym> and commit
+  time stamp of every source transaction can be configured on a per
+  transaction basis using
+  <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-XACT-SETUP"><code class="function">pg_replication_origin_xact_setup()</code></a>.
+  If that's done replication progress will persist in a crash safe
+  manner. Replay progress for all replication origins can be seen in the
+  <a class="link" href="view-pg-replication-origin-status.html" title="54.18. pg_replication_origin_status">
+   <code class="structname">pg_replication_origin_status</code>
+  </a> view. An individual origin's progress, e.g., when resuming
+  replication, can be acquired using
+  <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-PROGRESS"><code class="function">pg_replication_origin_progress()</code></a>
+  for any origin or
+  <a class="link" href="functions-admin.html#PG-REPLICATION-ORIGIN-SESSION-PROGRESS"><code class="function">pg_replication_origin_session_progress()</code></a>
+  for the origin configured in the current session.
+ </p><p>
+  In replication topologies more complex than replication from exactly one
+  system to one other system, another problem can be that it is hard to avoid
+  replicating replayed rows again. That can lead both to cycles in the
+  replication and inefficiencies. Replication origins provide an optional
+  mechanism to recognize and prevent that. When configured using the functions
+  referenced in the previous paragraph, every change and transaction passed to
+  output plugin callbacks (see <a class="xref" href="logicaldecoding-output-plugin.html" title="49.6. Logical Decoding Output Plugins">Section 49.6</a>)
+  generated by the session is tagged with the replication origin of the
+  generating session.  This allows treating them differently in the output
+  plugin, e.g., ignoring all but locally-originating rows.  Additionally
+  the <a class="link" href="logicaldecoding-output-plugin.html#LOGICALDECODING-OUTPUT-PLUGIN-FILTER-ORIGIN" title="49.6.4.7. Origin Filter Callback">
+  <code class="function">filter_by_origin_cb</code></a> callback can be used
+  to filter the logical decoding change stream based on the
+  source. While less flexible, filtering via that callback is
+  considerably more efficient than doing it in the output plugin.
+ </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="logicaldecoding-two-phase-commits.html" title="49.10. Two-phase Commit Support for Logical Decoding">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="server-programming.html" title="Part V. Server Programming">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="archive-modules.html" title="Chapter 51. Archive Modules">Next</a></td></tr><tr><td width="40%" align="left" valign="top">49.10. Two-phase Commit Support for Logical Decoding </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 51. Archive Modules</td></tr></table></div></body></html>
+\ No newline at end of file