rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Do some copy-editing on the docs for replication origins. 

Minor grammar and markup improvements.
This commit is contained in:
Tom Lane 2016-01-03 16:03:42 -05:00
parent 027989197a
commit c6aeba353a
2 changed files with 46 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
doc/src/sgml/func.sgml
View File

@ -17228,7 +17228,8 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
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>
@ -17239,9 +17240,11 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
</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">
@ -17401,11 +17404,11 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
<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 the passed in external
name, and create an internal id for it.
Create a replication origin with the given external
name, and return the internal id assigned to it.
</entry>
</row>
@ -17420,7 +17423,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
void
</entry>
<entry>
Delete a previously created replication origin, including the
Delete a previously created replication origin, including any
associated replay progress.
</entry>
</row>
@ -17433,10 +17436,10 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
<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
Lookup a replication origin by name and return the internal id. If no
corresponding replication origin is found an error is thrown.
</entry>
</row>
@ -17452,7 +17455,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
void
</entry>
<entry>
Configure the current session to be replaying from the passed in
Mark the current session as replaying from the given
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.
@ -17483,7 +17486,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
<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?
@ -17498,7 +17501,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
<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
@ -17519,8 +17522,8 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
void
</entry>
<entry>
Mark the current transaction to be replaying a transaction that has
committed at the passed in <acronym>LSN</acronym> and timestamp. Can
Mark the current transaction as replaying a transaction that has
committed at the given <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>.
@ -17554,7 +17557,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
void
</entry>
<entry>
Set replication progress for the passed in node to the passed in
Set replication progress for the given node to the given
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
@ -17570,10 +17573,10 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
<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 the passed in replication origin. The
Return the replay position for the given replication origin. The
parameter <parameter>flush</parameter> determines whether the
corresponding local transaction will be guaranteed to have been
flushed to disk or not.

47
doc/src/sgml/replication-origins.sgml
View File

@ -1,6 +1,7 @@
<!-- 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>
@ -11,46 +12,48 @@
<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 two common 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 origins consist out of a name and an <type>oid</type>. The name,
Replication origins have just two properties, a name and an OID. 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
The OID 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.
system catalog.
</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 like updating a row in
a table for every replayed transaction have problems like run-time overhead
bloat.
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.
</para>
<para>
@ -74,20 +77,20 @@
</para>
<para>
In more complex replication 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 allows to treat them differently in the output
plugin, e.g. ignoring all but locally originating rows. Additionally
generating session. This allows treating 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>