334 lines
13 KiB
Plaintext
334 lines
13 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 master server back online
|
|
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. Only changed blocks from relation files are copied;
|
|
all other files are copied in full, including configuration files. The
|
|
advantage of <application>pg_rewind</application> over taking a new base backup, or
|
|
tools like <application>rsync</application>, is that <application>pg_rewind</application> does
|
|
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>
|
|
<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, 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_wal</filename> directory, or
|
|
fetched on startup by configuring <xref linkend="guc-primary-conninfo"/> or
|
|
<xref linkend="guc-restore-command"/>. 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 rewinded
|
|
to become a standby again.
|
|
</para>
|
|
|
|
<para>
|
|
When the target server is started for the first time after running
|
|
<application>pg_rewind</application>, 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</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 configuring 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>
|
|
<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>
|
|
<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 not in recovery mode.
|
|
</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 synchronized data directory corrupt. Generally, this option is
|
|
useful for testing but should not be used when creating 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>--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>-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 diagnostics messages. Possible values are
|
|
<literal>always</literal>, <literal>auto</literal>,
|
|
<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>
|
|
|
|
<para>
|
|
When executing <application>pg_rewind</application> using an online
|
|
cluster as source which has been recently promoted, it is necessary
|
|
to execute a <command>CHECKPOINT</command> after promotion so as its
|
|
control file reflects up-to-date timeline information, which is used by
|
|
<application>pg_rewind</application> to check if the target cluster
|
|
can be rewound using the designated source cluster.
|
|
</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.
|
|
</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>).
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Copy all other files such as <filename>pg_xact</filename> and
|
|
configuration files from the source cluster to the target cluster
|
|
(everything except the relation files). 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. Any file or directory beginning with
|
|
<filename>pgsql_tmp</filename> is omitted, as well as are
|
|
<filename>backup_label</filename>,
|
|
<filename>tablespace_map</filename>,
|
|
<filename>pg_internal.init</filename>,
|
|
<filename>postmaster.opts</filename> and
|
|
<filename>postmaster.pid</filename>.
|
|
</para>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
Apply the WAL from the source cluster, starting from the checkpoint
|
|
created at failover. (Strictly speaking, <application>pg_rewind</application>
|
|
doesn't apply the WAL, it just creates a backup label file that
|
|
makes <productname>PostgreSQL</productname> start by replaying all WAL from
|
|
that checkpoint forward.)
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
</refentry>
|