in <xref linkend="functions-replication-table"> are for

controlling and interacting with replication features.

See <xref linkend="streaming-replication">,

<xref linkend="streaming-replication-slots">, <xref linkend="replication-origins">

<xref linkend="streaming-replication-slots">, and

<xref linkend="replication-origins">

for information about the underlying features. Use of these

functions is restricted to superusers.

</para>

</para>

<para>

The functions described in <xref linkend="functions-snapshot-synchronization">, <xref

linkend="functions-recovery-control">, and <xref

linkend="functions-admin-backup"> are also relevant for replication.

The functions described in

<xref linkend="functions-admin-backup">,

<xref linkend="functions-recovery-control">, and

<xref linkend="functions-snapshot-synchronization">

are also relevant for replication.

</para>

<table id="functions-replication-table">

<literal><function>pg_replication_origin_create(<parameter>node_name</parameter> <type>text</type>)</function></literal>

</entry>

<entry>

<parameter>internal_id</parameter> <type>oid</type>

<type>oid</type>

</entry>

<entry>

Create a replication origin with thepassed in external

name, andcreate an internal idfor it.

Create a replication origin with thegiven external

name, andreturn the internal idassigned to it.

</entry>

</row>

void

</entry>

<entry>

Delete a previously created replication origin, includingthe

Delete a previously created replication origin, includingany

associated replay progress.

</entry>

</row>

<literal><function>pg_replication_origin_oid(<parameter>node_name</parameter> <type>text</type>)</function></literal>

</entry>

<entry>

<parameter>internal_id</parameter> <type>oid</type>

<type>oid</type>

</entry>

<entry>

Lookup replication origin by name and return the internal id. If no

Lookupareplication origin by name and return the internal id. If no

corresponding replication origin is found an error is thrown.

</entry>

</row>

void

</entry>

<entry>

Configure the current sessionto bereplaying from thepassed in

Mark the current sessionasreplaying from thegiven

origin, allowing replay progress to be tracked. Use

<function>pg_replication_origin_session_reset</function> to revert.

Can only be used if no previous origin is configured.

<literal><function>pg_replication_origin_session_is_setup()</function></literal>

</entry>

<entry>

bool

<type>bool</type>

</entry>

<entry>

Has a replication origin been configured in the current session?

<literal><function>pg_replication_origin_session_progress(<parameter>flush</parameter> <type>bool</type>)</function></literal>

</entry>

<entry>

pg_lsn

<type>pg_lsn</type>

</entry>

<entry>

Return the replay position for the replication origin configured in

void

</entry>

<entry>

Mark the current transactionto be replaying a transaction that has

committed at thepassed in <acronym>LSN</acronym> and timestamp. Can

Mark the current transactionas replaying a transaction that has

committed at thegiven <acronym>LSN</acronym> and timestamp. Can

only be called when a replication origin has previously been

configured using

<function>pg_replication_origin_session_setup()</function>.

void

</entry>

<entry>

Set replication progress for thepassed innode to thepassed in

Set replication progress for thegivennode to thegiven

position. This primarily is useful for setting up the initial position

or a new position after configuration changes and similar. Be aware

that careless use of this function can lead to inconsistently

<literal><function>pg_replication_origin_progress(<parameter>node_name</parameter> <type>text</type>, <parameter>flush</parameter> <type>bool</type>)</function></literal>

</entry>

<entry>

pg_lsn

<type>pg_lsn</type>

</entry>

<entry>

Return the replay position for thepassed in replication origin. The

Return the replay position for thegiven replication origin. The

parameter <parameter>flush</parameter> determines whether the

corresponding local transaction will be guaranteed to have been

flushed to disk or not.

<!-- doc/src/sgml/replication-origins.sgml -->

<chapter id="replication-origins">

<title>Replication Progress Tracking</title>

<indexterm zone="replication-origins">

<primary>Replication Progress Tracking</primary>

</indexterm>

<para>

Replication origins are intended to make it easier to implement

logical replication solutions on top

of <xref linkend="logicaldecoding">. They provide a solution to two

common problems:

of <link linkend="logicaldecoding">logical decoding</link>.

They provide a solution to twocommon problems:

<itemizedlist>

<listitem><para>How to safely keep track of replication progress</para></listitem>

<listitem><para>How to change replication behavior, based on the

origin of a row; e.g. to avoid loops in bi-directional replication

setups</para></listitem>

<listitem>

<para>How to safely keep track of replication progress</para>

</listitem>

<listitem>

<para>How to change replication behavior based on the

origin of a row; for example, to prevent loops in bi-directional

replication setups</para>

</listitem>

</itemizedlist>

</para>

<para>

Replication originsconsist out ofa name and an<type>oid</type>. The name,

Replication originshave just two properties,a name and anOID. The name,

which is what should be used to refer to the origin across systems, is

free-form <type>text</type>. 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<type>oid</type> is used only to avoid having to store the long version

TheOID is used only to avoid having to store the long version

in situations where space efficiency is important. It should never be shared

between systems.

across systems.

</para>

<para>

Replication origins can be created using the

Replication origins can be created using the function

<link linkend="pg-replication-origin-create"><function>pg_replication_origin_create()</function></link>;

dropped using

<link linkend="pg-replication-origin-drop"><function>pg_replication_origin_drop()</function></link>;

and seen in the

<link linkend="catalog-pg-replication-origin"><structname>pg_replication_origin</structname></link>

catalog.

systemcatalog.

</para>

<para>

When replicating from one system to another (independent of the fact that

those two might be in the same cluster, or even same database) one

nontrivial part of building a replication solution is to keep track of

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 likeupdating a row in

a table for every replayed transaction have problems like run-time overhead

bloat.

successfully been replicated. Naive solutions to this, such asupdating a

row ina table for every replayed transaction, have problems like run-time

overhead and databasebloat.

</para>

<para>

</para>

<para>

Inmore complexreplication topologies than replication from exactly one

system to one other, another problem can be that it is hard to avoid

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 <xref linkend="logicaldecoding-output-plugin">)

generated by the session is tagged with the replication origin of the

generating session. This allowsto treat them differently in the output

plugin, e.g. ignoring all but locallyoriginating rows. Additionally

generating session. This allowstreating them differently in the output

plugin, e.g. ignoring all but locally-originating rows. Additionally

the <link linkend="logicaldecoding-output-plugin-filter-origin">

<function>filter_by_origin_cb</function></link> 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.

considerably more efficient than doing it in the output plugin.

</para>

</chapter>