pg_rewind docs: clarify handling of remote servers
This commit is contained in:
Bruce Momjian
parent
3ebc88e568
commit
878bd9accb
@ -16,7 +16,7 @@ PostgreSQL documentation
|
||||
|
||||
<refnamediv>
|
||||
<refname>pg_rewind</refname>
|
||||
<refpurpose>synchronize a <productname>PostgreSQL</productname> data directory with another data directory that was forked from the first one</refpurpose>
|
||||
<refpurpose>synchronize a <productname>PostgreSQL</productname> data directory with another data directory that was forked from it</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
@ -44,17 +44,18 @@ PostgreSQL documentation
|
||||
<application>pg_rewind</> is a tool for synchronizing a PostgreSQL cluster
|
||||
with another copy of the same cluster, after the clusters' timelines have
|
||||
diverged. A typical scenario is to bring an old master server back online
|
||||
after failover, as a standby that follows the new master.
|
||||
after failover as a standby that follows the new master.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The result is equivalent to replacing the target data directory with the
|
||||
source one. All files are copied, including configuration files. The
|
||||
source one. Only changed blocks from relation files are copied;
|
||||
all other files are copied in full, including configuration files. The
|
||||
advantage of <application>pg_rewind</> over taking a new base backup, or
|
||||
tools like <application>rsync</>, is that <application>pg_rewind</> does
|
||||
not require reading through all unchanged files in the cluster. That makes
|
||||
it a lot faster when the database is large and only a small portion of it
|
||||
differs between the clusters.
|
||||
not require reading through unchanged blocks in the cluster. This makes
|
||||
it a lot faster when the database is large and only a small
|
||||
fraction of blocks differ between the clusters.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -62,38 +63,37 @@ PostgreSQL documentation
|
||||
and target clusters to determine the point where they diverged, and
|
||||
expects to find WAL in the target cluster's <filename>pg_xlog</> directory
|
||||
reaching all the way back to the point of divergence. The point of divergence
|
||||
could be found either on target timeline, source timeline or their common
|
||||
can be found either on the target timeline, the source timeline, or their common
|
||||
ancestor. In the typical failover scenario where the target cluster was
|
||||
shut down soon after the divergence, that is not a problem, but if the
|
||||
target cluster had run for a long time after the divergence, the old WAL
|
||||
files might not be present anymore. In that case, they can be manually
|
||||
copied from the WAL archive to the <filename>pg_xlog</> directory. Fetching
|
||||
missing files from a WAL archive automatically is currently not supported.
|
||||
Besides, <application>pg_rewind</> use cases are not limited by failover.
|
||||
For instance, standby server could be promoted, run some writes and
|
||||
then be returned back as standby.
|
||||
shut down soon after the divergence, this is not a problem, but if the
|
||||
target cluster ran for a long time after the divergence, the old WAL
|
||||
files might no longer be present. In that case, they can be manually
|
||||
copied from the WAL archive to the <filename>pg_xlog</> directory, or
|
||||
fetched on startup by configuring <filename>recovery.conf</>. The use of
|
||||
<application>pg_rewind</> is not limited to failover, e.g. a standby
|
||||
server can be promoted, run some write transactions, and then rewinded
|
||||
to become a standby again.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When the target server is started up for the first time after running
|
||||
When the target server is started for the first time after running
|
||||
<application>pg_rewind</>, it will go into recovery mode and replay all
|
||||
WAL generated in the source server after the point of divergence.
|
||||
If some of the WAL was no longer available in the source server when
|
||||
<application>pg_rewind</> was run, and therefore could not be copied by
|
||||
<application>pg_rewind</> session, it needs to be made available when the
|
||||
target server is started up. That can be done by creating a
|
||||
<application>pg_rewind</> was run, and therefore could not be copied by the
|
||||
<application>pg_rewind</> session, it must be made available when the
|
||||
target server is started. This can be done by creating a
|
||||
<filename>recovery.conf</> file in the target data directory with a
|
||||
suitable <varname>restore_command</>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<application>pg_rewind</> requires that the target server either has
|
||||
the <xref linkend="guc-wal-log-hints"> option is enabled
|
||||
in <filename>postgresql.conf</> or that data checksums were enabled when
|
||||
the <xref linkend="guc-wal-log-hints"> option enabled
|
||||
in <filename>postgresql.conf</> or data checksums enabled when
|
||||
the cluster was initialized with <application>initdb</>. Neither of these
|
||||
are currently on by default.
|
||||
<xref linkend="guc-full-page-writes"> must also be enabled. That is the
|
||||
default.
|
||||
are currently on by default. <xref linkend="guc-full-page-writes">
|
||||
must also be set to <literal>on</>, but is enabled by default.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
@ -111,7 +111,7 @@ PostgreSQL documentation
|
||||
<listitem>
|
||||
<para>
|
||||
This option specifies the target data directory that is synchronized
|
||||
with the source. The target server must shut down cleanly before
|
||||
with the source. The target server must be shut down cleanly before
|
||||
running <application>pg_rewind</application>
|
||||
</para>
|
||||
</listitem>
|
||||
@ -121,9 +121,9 @@ PostgreSQL documentation
|
||||
<term><option>--source-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies path to the data directory of the source server, to
|
||||
synchronize the target with. This option requires the source server
|
||||
to be cleanly shut down.
|
||||
Specifies the file system path to the data directory of the source
|
||||
server to synchronize the target with. This option requires the
|
||||
source server to be cleanly shut down.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@ -135,8 +135,8 @@ PostgreSQL documentation
|
||||
Specifies a libpq connection string to connect to the source
|
||||
<productname>PostgreSQL</> server to synchronize the target with.
|
||||
The connection must be a normal (non-replication) connection
|
||||
with superuser access. This option requires the server to be running
|
||||
and not in recovery mode.
|
||||
with superuser access. This option requires the source
|
||||
server to be running and not in recovery mode.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@ -157,7 +157,7 @@ PostgreSQL documentation
|
||||
<listitem>
|
||||
<para>
|
||||
Enables progress reporting. Turning this on will deliver an approximate
|
||||
progress report while copying data over from the source cluster.
|
||||
progress report while copying data from the source cluster.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@ -205,38 +205,42 @@ PostgreSQL documentation
|
||||
<title>How it works</title>
|
||||
|
||||
<para>
|
||||
The basic idea is to copy everything from the new cluster to the old
|
||||
cluster, except for the blocks that we know to be the same.
|
||||
The basic idea is to copy all file system-level changes from the source
|
||||
cluster to the target cluster:
|
||||
</para>
|
||||
|
||||
<procedure>
|
||||
<step>
|
||||
<para>
|
||||
Scan the WAL log of the old cluster, starting from the last checkpoint
|
||||
before the point where the new cluster's timeline history forked off
|
||||
from the old cluster. For each WAL record, make a note of the data
|
||||
blocks that were touched. This yields a list of all the data blocks
|
||||
that were changed in the old cluster, after the new cluster forked off.
|
||||
Scan the WAL log of the target cluster, starting from the last
|
||||
checkpoint before the point where the source cluster's timeline
|
||||
history forked off from the target cluster. For each WAL record,
|
||||
record each data block that was touched. This yields a list of all
|
||||
the data blocks that were changed in the target cluster, after the
|
||||
source cluster forked off.
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
Copy all those changed blocks from the new cluster to the old cluster.
|
||||
Copy all those changed blocks from the source cluster to
|
||||
the target cluster, either using direct file system access
|
||||
(<option>--source-pgdata</>) or SQL (<option>--source-server</>).
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
Copy all other files such as <filename>clog</filename> and configuration files from the new cluster
|
||||
to the old cluster, everything except the relation files.
|
||||
Copy all other files such as <filename>pg_clog</filename> and
|
||||
configuration files from the source cluster to the target cluster
|
||||
(everything except the relation files).
|
||||
</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>
|
||||
Apply the WAL from the new cluster, starting from the checkpoint
|
||||
Apply the WAL from the source cluster, starting from the checkpoint
|
||||
created at failover. (Strictly speaking, <application>pg_rewind</>
|
||||
doesn't apply the WAL, it just creates a backup label file indicating
|
||||
that when <productname>PostgreSQL</> is started, it will start replay
|
||||
from that checkpoint and apply all the required WAL.)
|
||||
doesn't apply the WAL, it just creates a backup label file that
|
||||
makes <productname>PostgreSQL</> start by replaying all WAL from
|
||||
that checkpoint forward.)
|
||||
</para>
|
||||
</step>
|
||||
</procedure>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user