<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>,
      <filename>postmaster.pid</filename> and
      <filename>.DS_Store</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>