<refnamediv>

<refname>pg_rewind</refname>

<refpurpose>synchronize a <productname>PostgreSQL</productname> data directory with another data directory that was forked fromthe first one</refpurpose>

<refpurpose>synchronize a <productname>PostgreSQL</productname> data directory with another data directory that was forked fromit</refpurpose>

</refnamediv>

<refsynopsisdiv>

<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 throughallunchangedfiles 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 unchangedblocks 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</> 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_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 onthetarget timeline,thesource 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 clusterhad run for a long time after the divergence, the old WAL

files mightnotbe present anymore. In that case, they can be manually

copied from the WAL archive to the <filename>pg_xlog</> directory. Fetching

Besides,<application>pg_rewind</>use cases arenot limitedby failover.

For instance, standbyservercould be promoted, run somewritesand

then be returned back asstandby.

shut down soon after the divergence,this is not a problem, but if the

target clusterran for a long time after the divergence, the old WAL

files mightno longerbe present. In that case, they can be manually

copied from the WAL archive to the <filename>pg_xlog</> directory, or

<application>pg_rewind</>isnot limitedto failover, e.g. a standby

servercan be promoted, run somewrite transactions,and then rewinded

to become astandby again.

</para>

<para>

When the target server is startedupfor 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, itneeds 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, itmust 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"> optionisenabled

in <filename>postgresql.conf</> orthatdata 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>

<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 mustbeshut down cleanly before

running <application>pg_rewind</application>

</para>

</listitem>

<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.

Specifiesthe file systempath to the data directory of the source

server tosynchronize the target with. This option requires the

source serverto be cleanly shut down.

</para>

</listitem>

</varlistentry>

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 theserver to be running

and not in recovery mode.

with superuser access. This option requires thesource

server to be runningand not in recovery mode.

</para>

</listitem>

</varlistentry>

<listitem>

<para>

Enables progress reporting. Turning this on will deliver an approximate

progress report while copying dataoverfrom the source cluster.

progress report while copying data from the source cluster.

</para>

</listitem>

</varlistentry>

<title>How it works</title>

<para>

The basic idea is to copyeverything from the new cluster totheold

cluster, except for the blocks that we knowtobethesame.

The basic idea is to copyall file system-level changes fromthesource

clusterto thetarget 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 thenew cluster, starting from the checkpoint

Apply the WAL from thesource cluster, starting from the checkpoint

created at failover. (Strictly speaking, <application>pg_rewind</>

doesn't apply the WAL, it just creates a backup label fileindicating

that when<productname>PostgreSQL</>is started, it will start replay

fromthat checkpointand apply all the required WAL.)

doesn't apply the WAL, it just creates a backup label filethat

makes<productname>PostgreSQL</>start by replaying all WAL from

that checkpointforward.)

</para>

</step>

</procedure>