411 lines
16 KiB
Plaintext
411 lines
16 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/pg_rewind.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-pgrewind">
|
|
<indexterm zone="app-pgrewind">
|
|
<primary>pg_rewind</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle><application>pg_rewind</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_rewind</refname>
|
|
<refpurpose>synchronize a <productname>PostgreSQL</productname> data directory with another data directory that was forked from it</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pg_rewind</command>
|
|
<arg rep="repeat"><replaceable>option</replaceable></arg>
|
|
<group choice="plain">
|
|
<group choice="req">
|
|
<arg choice="plain"><option>-D</option></arg>
|
|
<arg choice="plain"><option>--target-pgdata</option></arg>
|
|
</group>
|
|
<replaceable> directory</replaceable>
|
|
<group choice="req">
|
|
<arg choice="plain"><option>--source-pgdata=<replaceable>directory</replaceable></option></arg>
|
|
<arg choice="plain"><option>--source-server=<replaceable>connstr</replaceable></option></arg>
|
|
</group>
|
|
</group>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<application>pg_rewind</application> 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 primary server back online
|
|
after failover as a standby that follows the new primary.
|
|
</para>
|
|
|
|
<para>
|
|
After a successful rewind, the state of the target data directory is
|
|
analogous to a base backup of the source data directory. Unlike taking
|
|
a new base backup or using a tool like <application>rsync</application>,
|
|
<application>pg_rewind</application> does not require comparing or copying
|
|
unchanged relation blocks in the cluster. Only changed blocks from existing
|
|
relation files are copied; all other files, including new relation files,
|
|
configuration files, and WAL segments, are copied in full. As such the
|
|
rewind operation is significantly faster than other approaches when the
|
|
database is large and only a small fraction of blocks differ between the
|
|
clusters.
|
|
</para>
|
|
|
|
<para>
|
|
<application>pg_rewind</application> examines the timeline histories of the source
|
|
and target clusters to determine the point where they diverged, and
|
|
expects to find WAL in the target cluster's <filename>pg_wal</filename> directory
|
|
reaching all the way back to the point of divergence. The point of divergence
|
|
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, this is not a problem, but if the
|
|
target cluster ran for a long time after the divergence, its old WAL
|
|
files might no longer be present. In this case, you can manually copy them
|
|
from the WAL archive to the <filename>pg_wal</filename> directory, or run
|
|
<application>pg_rewind</application> with the <literal>-c</literal> option to
|
|
automatically retrieve them from the WAL archive. The use of
|
|
<application>pg_rewind</application> is not limited to failover, e.g., a standby
|
|
server can be promoted, run some write transactions, and then rewound
|
|
to become a standby again.
|
|
</para>
|
|
|
|
<para>
|
|
After running <application>pg_rewind</application>, WAL replay needs to
|
|
complete for the data directory to be in a consistent state. When the
|
|
target server is started again it will enter archive recovery and replay
|
|
all WAL generated in the source server from the last checkpoint before
|
|
the point of divergence. If some of the WAL was no longer available in the
|
|
source server when <application>pg_rewind</application> was run, and
|
|
therefore could not be copied by the <application>pg_rewind</application>
|
|
session, it must be made available when the target server is started.
|
|
This can be done by creating a <filename>recovery.signal</filename> file
|
|
in the target data directory and by configuring a suitable
|
|
<xref linkend="guc-restore-command"/> in
|
|
<filename>postgresql.conf</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
<application>pg_rewind</application> requires that the target server either has
|
|
the <xref linkend="guc-wal-log-hints"/> option enabled
|
|
in <filename>postgresql.conf</filename> or data checksums enabled when
|
|
the cluster was initialized with <application>initdb</application>. Neither of these
|
|
are currently on by default. <xref linkend="guc-full-page-writes"/>
|
|
must also be set to <literal>on</literal>, but is enabled by default.
|
|
</para>
|
|
|
|
<warning>
|
|
<title>Warning: Failures while Rewinding</title>
|
|
<para>
|
|
If <application>pg_rewind</application> fails while processing, then
|
|
the data folder of the target is likely not in a state that can be
|
|
recovered. In such a case, taking a new fresh backup is recommended.
|
|
</para>
|
|
|
|
<para>
|
|
As <application>pg_rewind</application> copies configuration files
|
|
entirely from the source, it may be required to correct the configuration
|
|
used for recovery before restarting the target server, especially if
|
|
the target is reintroduced as a standby of the source. If you restart
|
|
the server after the rewind operation has finished but without configuring
|
|
recovery, the target may again diverge from the primary.
|
|
</para>
|
|
|
|
<para>
|
|
<application>pg_rewind</application> will fail immediately if it finds
|
|
files it cannot write directly to. This can happen for example when
|
|
the source and the target server use the same file mapping for read-only
|
|
SSL keys and certificates. If such files are present on the target server
|
|
it is recommended to remove them before running
|
|
<application>pg_rewind</application>. After doing the rewind, some of
|
|
those files may have been copied from the source, in which case it may
|
|
be necessary to remove the data copied and restore back the set of links
|
|
used before the rewind.
|
|
</para>
|
|
</warning>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>
|
|
<application>pg_rewind</application> accepts the following command-line
|
|
arguments:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
|
|
<term><option>--target-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
This option specifies the target data directory that is synchronized
|
|
with the source. The target server must be shut down cleanly before
|
|
running <application>pg_rewind</application>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--source-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
|
|
<varlistentry>
|
|
<term><option>--source-server=<replaceable class="parameter">connstr</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a libpq connection string to connect to the source
|
|
<productname>PostgreSQL</productname> server to synchronize the target
|
|
with. The connection must be a normal (non-replication) connection
|
|
with a role having sufficient permissions to execute the functions
|
|
used by <application>pg_rewind</application> on the source server
|
|
(see Notes section for details) or a superuser role. This option
|
|
requires the source server to be running and accepting connections.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-R</option></term>
|
|
<term><option>--write-recovery-conf</option></term>
|
|
<listitem>
|
|
<para>
|
|
Create <filename>standby.signal</filename> and append connection
|
|
settings to <filename>postgresql.auto.conf</filename> in the output
|
|
directory. <literal>--source-server</literal> is mandatory with
|
|
this option.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-n</option></term>
|
|
<term><option>--dry-run</option></term>
|
|
<listitem>
|
|
<para>
|
|
Do everything except actually modifying the target directory.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-N</option></term>
|
|
<term><option>--no-sync</option></term>
|
|
<listitem>
|
|
<para>
|
|
By default, <command>pg_rewind</command> will wait for all files
|
|
to be written safely to disk. This option causes
|
|
<command>pg_rewind</command> to return without waiting, which is
|
|
faster, but means that a subsequent operating system crash can leave
|
|
the data directory corrupt. Generally, this option is useful for
|
|
testing but should not be used on a production
|
|
installation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-P</option></term>
|
|
<term><option>--progress</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enables progress reporting. Turning this on will deliver an approximate
|
|
progress report while copying data from the source cluster.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-c</option></term>
|
|
<term><option>--restore-target-wal</option></term>
|
|
<listitem>
|
|
<para>
|
|
Use <varname>restore_command</varname> defined in the target cluster
|
|
configuration to retrieve WAL files from the WAL archive if these
|
|
files are no longer available in the <filename>pg_wal</filename>
|
|
directory.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--config-file=<replaceable class="parameter">filename</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Use the specified main server configuration file for the target
|
|
cluster. This affects <application>pg_rewind</application> when
|
|
it uses internally the <application>postgres</application> command
|
|
for the rewind operation on this cluster (when retrieving
|
|
<varname>restore_command</varname> with the option
|
|
<option>-c/--restore-target-wal</option> and when forcing a
|
|
completion of crash recovery).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--debug</option></term>
|
|
<listitem>
|
|
<para>
|
|
Print verbose debugging output that is mostly useful for developers
|
|
debugging <application>pg_rewind</application>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--no-ensure-shutdown</option></term>
|
|
<listitem>
|
|
<para>
|
|
<application>pg_rewind</application> requires that the target server
|
|
is cleanly shut down before rewinding. By default, if the target server
|
|
is not shut down cleanly, <application>pg_rewind</application> starts
|
|
the target server in single-user mode to complete crash recovery first,
|
|
and stops it.
|
|
By passing this option, <application>pg_rewind</application> skips
|
|
this and errors out immediately if the server is not cleanly shut
|
|
down. Users are expected to handle the situation themselves in that
|
|
case.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-V</option></term>
|
|
<term><option>--version</option></term>
|
|
<listitem><para>Display version information, then exit.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-?</option></term>
|
|
<term><option>--help</option></term>
|
|
<listitem><para>Show help, then exit.</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<para>
|
|
When <option>--source-server</option> option is used,
|
|
<application>pg_rewind</application> also uses the environment variables
|
|
supported by <application>libpq</application> (see <xref linkend="libpq-envars"/>).
|
|
</para>
|
|
|
|
<para>
|
|
The environment variable <envar>PG_COLOR</envar> specifies whether to use
|
|
color in diagnostic messages. Possible values are
|
|
<literal>always</literal>, <literal>auto</literal> and
|
|
<literal>never</literal>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
When executing <application>pg_rewind</application> using an online
|
|
cluster as source, a role having sufficient permissions to execute the
|
|
functions used by <application>pg_rewind</application> on the source
|
|
cluster can be used instead of a superuser. Here is how to create such
|
|
a role, named <literal>rewind_user</literal> here:
|
|
<programlisting>
|
|
CREATE USER rewind_user LOGIN;
|
|
GRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind_user;
|
|
GRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user;
|
|
GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user;
|
|
GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<refsect2>
|
|
<title>How It Works</title>
|
|
|
|
<para>
|
|
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 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. If some of the WAL files are no longer
|
|
available, try re-running <application>pg_rewind</application> with
|
|
the <option>-c</option> option to search for the missing files in
|
|
the WAL archive.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Copy all those changed blocks from the source cluster to
|
|
the target cluster, either using direct file system access
|
|
(<option>--source-pgdata</option>) or SQL (<option>--source-server</option>).
|
|
Relation files are now in a state equivalent to the moment of the last
|
|
completed checkpoint prior to the point at which the WAL timelines of the
|
|
source and target diverged plus the current state on the source of any
|
|
blocks changed on the target after that divergence.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Copy all other files, including new relation files, WAL segments,
|
|
<filename>pg_xact</filename>, and configuration files from the source
|
|
cluster to the target cluster. Similarly to base backups, the contents
|
|
of the directories <filename>pg_dynshmem/</filename>,
|
|
<filename>pg_notify/</filename>, <filename>pg_replslot/</filename>,
|
|
<filename>pg_serial/</filename>, <filename>pg_snapshots/</filename>,
|
|
<filename>pg_stat_tmp/</filename>, and <filename>pg_subtrans/</filename>
|
|
are omitted from the data copied from the source cluster. The files
|
|
<filename>backup_label</filename>,
|
|
<filename>tablespace_map</filename>,
|
|
<filename>pg_internal.init</filename>,
|
|
<filename>postmaster.opts</filename>, and
|
|
<filename>postmaster.pid</filename>, as well as any file or directory
|
|
beginning with <filename>pgsql_tmp</filename>, are omitted.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Create a <filename>backup_label</filename> file to begin WAL replay at
|
|
the checkpoint created at failover and configure the
|
|
<filename>pg_control</filename> file with a minimum consistency LSN
|
|
defined as the result of <literal>pg_current_wal_insert_lsn()</literal>
|
|
when rewinding from a live source or the last checkpoint LSN when
|
|
rewinding from a stopped source.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
When starting the target, <productname>PostgreSQL</productname> replays
|
|
all the required WAL, resulting in a data directory in a consistent
|
|
state.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
</refentry>
|